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

Most FOSS documentation is abysmal

[hduff]

That's how I got my entree into writing about Linux. Programmers are very smart, but not very eloquent and they are also very poor teachers.

There are any number of rules and guidelines for writing documentation, most of which are ignored since documentation is often the red-headed stepchild of the project.

Documentation should tell a story clearly and help the reader understand the 'why' and 'how' as well as the 'what'.

An excellent post, with one omission: pictures.

[QilessQi]

I produce a lot of documentation along with my coding, and the one thing that makes it palatable (even to me, re-reading it) are illustrations.

I'm not talking about UML class or activity diagrams, although those things are great where appropriate. It could be anything relevant to getting your point across, like a fragment of a database table showing sample data so people can visualize how a group of tables will work together. Screen grabs with arrows and circles.

My rule of thumb: if I ever find myself drawing a picture on a whiteboard as I'm explaining my module to someone, I immediately stop and take a picture of the diagram I just drew, and ASAP afterwards I turn that picture into an illustration in the user docs. Then next time I can just whip out the docs and point to the illustration.