search

ProjetPP / Documentation

Documentation and protocol specification of the Projet Pensées Profondes
Creative Commons Zero v1.0 Universal
7 stars 1 forks source link

Nicer display for the documentation #55

Open Ezibenroc opened 9 years ago

Ezibenroc commented 9 years ago

Our documentation is an unstructured list of *.md files in a GitHub repository: this is unattractive.

We should think about a new way to display it. There is two possibilities:

progval commented 9 years ago

There are / will be links to these files

Ezibenroc commented 9 years ago

Bump. The documentation is messy...

progval commented 9 years ago

What is the issue with using this as an index? https://github.com/ProjetPP/Documentation/blob/master/getting-started.md

progval commented 9 years ago

Should we rename it to README.md?

Ezibenroc commented 9 years ago

Don't you think that a wiki like this or this is nicer?

progval commented 9 years ago

You can do that without a wiki.

waldyrious commented 9 years ago

I also vote for using a GitHub wiki. It's still a git repository, we get an automatic index for free (no need to keep it manually in sync), the index is always visible on the sidebar, and the barrier to contribution is lower. The way I see it, it's only upsides :)

Ezibenroc commented 9 years ago

You can do that without a wiki.

Why should we do without a wiki? I don't see any good reason...

I agree with @waldyrious.

progval commented 9 years ago

Because that would mean having an empty repository just for hosting the wiki

Tpt commented 9 years ago

I think that specifications should be kept in the repository in order to be still able to use the pull request system for changes.

Ezibenroc commented 9 years ago

Because that would mean having an empty repository just for hosting the wiki

No, we can create the wiki in this repository.

I think that specifications should be kept in the repository in order to be still able to use the pull request system for changes.

I think specifications changes should be discussed on the forum, since they concern the whole project.

In fact, I think it would be even better to have this wiki on our website rather than on github.

waldyrious commented 9 years ago

Because that would mean having an empty repository just for hosting the wiki

In that case, why not using the wiki in the website repository, https://github.com/ProjetPP/projetpp.github.io? (Also recall that the wiki is itself a git repo, located at https://github.com/<user>/<repo>.wiki.git)

In fact, I think it would be even better to have this wiki on our website rather than on github.

Why would that be better? For visibility, I suppose? But a link in the top menu should make the github wiki just as discoverable, and we'd get to keep all the niceties that otherwise would have to be maintained by hand (support of several markup formats, automatic index on the sidebar, unified (github) accounts for both wiki editors and code contributors, etc.)

Ezibenroc commented 9 years ago

Why would that be better? For visibility, I suppose? But a link in the top menu should make the github wiki just as discoverable, and we'd get to keep all the niceties that otherwise would have to be maintained by hand (support of several markup formats, automatic index on the sidebar, unified (github) accounts for both wiki editors and code contributors, etc.

I searched if there was a way to have a github wiki integrated on a github webpage, but did not find anything good. So I think we should do as you propose: do a github wiki (in this repository if we keep it, in the website repository otherwise), and put a link on the website (thus moving the page technical overview into the wiki).

@ProjetPP/owners what do you think?

robocop commented 9 years ago

I vote for a github wiki