README is getting loooonnnggg

[henrikbjorn]

How about utilizing the WIKI system provided by GitHub to create a page per section.

The wiki system got an overhaul recently and is much more user friendly and provides links to headlines etc.

[armandabric]

What about using the automatic gh-page ? This allow to keep working with PR for proposal.

[mnapoli]

We could split the single README into several files. I'm too in favor of keeping everything into the repo as it's where we land, and we can do PRs and stuff.

Regarding gh-pages, that could be awesome indeed to turn the markdown files into a website (à la "PHP the right way").

I have developed Couscous by the way which does exactly that: http://mnapoli.fr/Couscous/

Examples of websites built using Couscous:

• PHP-DI, markdown files are in the master branch: https://github.com/mnapoli/PHP-DI
• MyCLabs\ACL, markdown files are also in the master branch: https://github.com/myclabs/ACL
• Couscous itself is built like that

That could be a simple solution if we wanted to use gh-pages.

[romaricdrigon]

Couscous looks really nice. Keeping MD & files in a repo are good for contributing, having HTML on a separated branch is clean.

[henrikbjorn]

We could just use Jekyll, and have GitHub do the work of generating, hosting etc..

[mnapoli]

Couscous == Jekyll but simpler, and in PHP. The website would still be hosted in GitHub pages.

I have nothing against Jekyll though (except its complexity), I was just shamelessly promoting something I wrote :p (and I'll stop doing it, I don't want to derail the conversation)

[tyx]

No problem for any solution which drives to better readibility by keeping contribution easy.