Hillel Wayne has some opinions on documentation:
Hillel advises against Markdown – what to use instead:
What to use instead
LaTeX.
Kidding. LaTeX is extremely powerful but also a nightmare to use and almost impossible to turn into online documentation.
A better answer is reStructuredText or RST. This is almost always used with the Sphinx documentation generator. It gets around the issues markdown has by having special syntax for semantic properties and extensions. Sphinx uses them to add cross-documentation references without having to add a second layer of preprocessing syntax.
RST may be the correct solution for a large product like a book type site, but for collaborative documentation, Markdown is more universal and perhaps more likely to get maintained. It’s really hard to get most people to do any documentation these days, so in reality, maybe most documentation is a solo effort anyway – hmm …
The learntla site he has been working on looks quite good: