Tuesday, January 10, 2006
How much is too much?
When writing documentation, there's always a temptation to document everything. Take, for example, the manual that I'm currently working on. When I took over this project, the manual weighed in at a whopping 917 pages. I've since reduced its girth to less that half of that.
But what I couldn't get over were the 21 pages devoted to explaining the documentation and the online help. Were these really necessary? Or was it just the case of a writer trying to make his work seem more important and profound than it actually was? Take these sentences:
The secret to writing good documentation is knowing what needs to be documented and what doesn't. Some things are quite obvious, even to someone with limited experience with computers. Some things aren't. The key is to focus on what's not obvious, and to make what's difficult easier.
But what I couldn't get over were the 21 pages devoted to explaining the documentation and the online help. Were these really necessary? Or was it just the case of a writer trying to make his work seem more important and profound than it actually was? Take these sentences:
The User Guide Index was referenced to the 4th degree and double posted. The result is a professional index, set according to the standards of the Indexing and Abstracting Society, that is professionally written rather than simply generated.To be honest, I don't know what "referenced to the 4th degree and double posted" means. It probably has some meaning in the world of indexing, but I suspect that most readers couldn't care less about how the index was created. They just want one that's usable.
The secret to writing good documentation is knowing what needs to be documented and what doesn't. Some things are quite obvious, even to someone with limited experience with computers. Some things aren't. The key is to focus on what's not obvious, and to make what's difficult easier.
