Language: Putting Words to Use

Think of some of the uses of language. Think of how great ideas and concepts can be shared amongst people. Then think of some of the seemingly less great uses of the English language.

Like computer and software documentation.

Well let me be fair. Amongst all the horrible documentation there are some very good ones. But I don't want to point you to some good documentation and say that's that. I'd rather point you towards some writing on how to create good documentation instead.

First up is Writing Great Documentation by Jacob Kaplan-Moss. Next up is Brian Forte's How to write really good documentation: Four rules and an axiom which takes us through the rewrite of a couple problematic paragraphs while explaining good documentation.

Lastly there is Writing and Programming - Next of Kin from techwriter.dk which summarizes something I've said for years. That writing and programming use the same parts of your brain and follow the same sort of steps. I've used programming to explain writing to techies and writing to explain programming to non-techies. They really are next of kin.