write in Markdown, the same formatting syntax we use on Stack Overflow. Because the documents are plain text, they can live alongside code in version control. That’s useful.
I render the documents to HTML and PDF with the swiss army knife Pandoc. With a short stylesheet, these look better than documents from word processors.
If we’re talking about technical documentation, in my mind there are two separate kinds of documentation, of which you should have both. For libraries and APIs you have auto-generated documentation describing the function calls and types this is useful for refernece, but you also need prosy user guide/tutorial style documentation that can be read top to bottom. :
- Pandoc low level API reference for hackers
- Pandoc prosy user guide for users (and hackers)
Addendum: You can use Sphinx for both kinds of documentation. The output is beautiful
https://readthedocs.org/ will get you started with Sphinx and host the site for you
both. For libraries and APIs you have auto-generated documentation describing the function calls and types this is useful for refernece, but you also need prosy user guide/tutorial style documentation that can be read top to bottom. :
- Pandoc low level API reference for hackers
- Pandoc prosy user guide for users (and hackers)
Addendum: You can use Sphinx for both kinds of documentation. The output is beautiful
https://readthedocs.org/ will get you started with Sphinx and host the site for you
both. For libraries and APIs you have auto-generated documentation describing the function calls and types this is useful for refernece, but you also need prosy user guide/tutorial style documentation that can be read top to bottom. :
- Pandoc low level API reference for hackers
- Pandoc prosy user guide for users (and hackers)
Addendum: You can use Sphinx for both kinds of documentation. The output is beautiful
https://readthedocs.org/ will get you started with Sphinx and host the site for you