Writing Good Documentation
How to write good documentation#
Use these 3 links:
- https://jacobian.org/2009/nov/10/what-to-write/
- http://stevelosh.com/blog/2013/09/teach-dont-tell/
- https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
Auto-generated documentation is almost worthless
At best it’s a slightly improved version of simply browsing through the source, but most of the time it’s easier just to read the source than to navigate the bullshit that these autodoc tools produce
There’s no substitute for documentation written, organized, and edited by hand
I’ll even go further and say that auto-generated documentation is worse than useless: it lets maintainers fool themselves into thinking they have documentation, thus putting off actually writing good reference by hand