Writing Documentation: Teach, Don't Tell

Programmer Steve Losh has written a lengthy explanation of what separates good documentation from bad, and how to go about planning and writing documentation that will actually help people. His overarching point is that documentation should be used to teach, not to dump excessive amounts of unstructured information onto a user. Losh takes many of the common documentation tropes — "read the source," "look at the tests," "read the docstrings" — and makes analogies with learning everyday skills to show how silly they can be. "This is your driving teacher, Ms. Smith. ... If you have any questions about a part of the car while you’re driving, you can ask her and she’ll tell you all about that piece. Here are the keys, good luck!" He has a similar opinion of API strings: "API documentation is like the user’s manual of a car. When something goes wrong and you need to replace a tire it’s a godsend. But if you’re learning to drive it’s not going to help you because people don’t learn by reading alphabetized lists of disconnected information." Losh's advice for wikis is simple and straightforward: "They are bad and terrible. Do not use them."

Comments

Re:Source code

[LinuxIsGarbage]

And for no arguments. Or at least print what is required to get help

C:\>app
Crappy app 0.0.0.1a
GPL 2 (If you don't like it fix it yourself

For help type -?

C:\>app /?
Crappy app 0.0.0.1a
GPL 2 (If you don't like it fix it yourself

I said enter -?, not /? This program was barely ported using cygwin, so you have to use *NIX arguments
Don't like it, fix it yourself
C:\>_

Re:Source code

[VortexCortex]

-h? Next time, use all three of these: -?, -help, --help. I'm probably not going to try throwing -h at a program without having a clue what it might do.

Then use the damn manual. That's why we write them. If you want to know how to use the manual, use the manual:
$ man man

... hmm, That gives me an idea.
$ man woman
No manual entry for woman

Yep. It knows everything!