Nicer display for the documentation

[Ezibenroc]

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:

• A GitHub wiki.
• Our website.

[progval]

There are / will be links to these files

[Ezibenroc]

Bump.
The documentation is messy...

[progval]

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

[progval]

Should we rename it to README.md?

[Ezibenroc]

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

[progval]

You can do that without a wiki.

[waldyrious]

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]

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]

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

[Tpt]

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]

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]

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]

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]

I vote for a github wiki