Technical documentation. I doubt it's something any of us would list as our favorite genre, either to write or to read. But it's one of those necessities we often curse then begrudgingly accept when we have to wade our way through it in order to solve a problem or when we have to write it in order to explain a technical product.
Good documentation is hard to write. There are number of forms in which technical documents can take: very general or high-level overviews, step-by-step walkthroughs, or auto-generated documents, for example. Add this to the variety of users who might need your documentation – their different needs, technical expertise, learning styles – and you'll probably find there is really no one single format that will work for everyone.
Writing for the Right Audience
With that in mind, the first thing you need to consider when writing documentation for your project is audience. An end-user will want documentation that's primarily instructional – a How-To. While some technical concepts can be mentioned (and explained), the emphasis should be on the interface, not on the back-end. Another programmer looking at the documentation will want additional information: technical details of how program elements work, where in the code actions occur, and if applicable, how to extend the code. Writing for one audience shouldn't preclude writing for the other, but you should consider separate documents – the user's technical documentation and the technician's technical documentation, so to speak.
Types of Documentation
In Jacob Kaplan-Moss guide to writing great documentation, he points to three categories for documentation: tutorials, topical guides, and reference guides.
Tutorials: Tutorials are important as they are often a first impression when someone uses a new tech tool. As we've written about before, there are a number of tools to help you make good tutorials. But if you're writing one, Kaplan-Moss recommends tutorials be quick and easy – but not too easy – and demonstrate how your project "feels." Example: the user guide for the recently release Anthologize blog-to-eBook tool. Note the screenshots that accompany each step.
Topical Guides: These are, in the words, of Kaplan-Moss, "the meat of your documentation." While a tutorial provides an introduction to high-level concepts, topical guides are for those who want to dig deeper. Their main goal should be comprehensiveness. As Kaplan-Moss notes, books often outshine the official documentation, which is unfortunate as the latter can be kept better up-to-date. Example: Django documentation – everything you need to know about Django (and then some).
Reference Guides: Reference guides are designed for those users who understand some of the "how" found in the guides, but are looking for information. "These should be designed for those who already know how to use some API, but need to look up the exact arguments some function takes, or how a particular setting influences behavior, etc. It's important to point out that reference material is not in any way a substitute for good tutorials and guides!" Auto-generated documentation is a start, but without additional writing, editing, organization, it's unlikely to really answer anyone's questions.
And just because it's "technical writing" doesn't mean that you should forgo poetic language, grammar and spell-check. OK, well, at least please edit for spelling and grammar.
Photo credits: Flickr user John Norton
…
Cheers!…
