Writing Documentation: Teach, Don't Tell 211
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."
'help' (Score:4, Interesting)
I agree with your superficial point...who would have thunk it indeed
However, I think it is still a distinction without a difference, one that only causes more confusion.
You and I know what 'documentation' in the computing sense means, but it's not a logical concept for a non-techie.
'documentation' in computing can be as simple as the coder showing his/her work and making a formal log of changes and bug reports/fixes
however, and here is where the problem happens...what constitutes 'sufficient documentation' for a coder is *not* sufficient for a user!
the problem is, that to bridge the gap, most programmers (who are not at all schooled in education theory & by nature tend anti-social) must create some sort of 'document' beyond the 'documentation' for the end user
sometimes this takes the form a 'tutorial'
a 'tutorial' is not full instructions...it is a real-time step-by step *demonstration* which may have supplimentary material that is actually instructions
ex: I can make a video with the steps to start a car, put it in gear and how the brake and throttle work...a person, with *nothing* else but that video and factory plans of the car *could* learn to use it...but calling a basic video and factory plans 'instrucitons' is insulting!
'documentation' can be helpful
'tutorials' can be helpful
'help' menus can be helpful
even so, its not a full user manual that an end user in other industries would expect
the computing industry has decades of work in this area I fear...so many have gotten used to doing it a bad way
Most FOSS documentation is abysmal (Score:5, Interesting)
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. (Score:5, Interesting)
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.
Re:Source code (Score:4, Interesting)
-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.
For non-Windows systems:
-h is Valid
-? is Invalid as '?' is a special parameter that may be expanded by the shell
-help is Invalid on GNU/Linux (though used often by ported applications)
--help is Invalid on older Unix systems.
For newer Windows systems:
-? is Valid (and mandatory)
-Help is Valid (and mandatory)
--help is Invalid
-help is Valid
-h is Valid
-h is the safest option