« videoconv.sh, Part III | Main | Looking out the window »
July 09, 2004
Why tech writers don't categorize like readers
Vesa Purho suggests in Documentation or Training? — Boundaries Get Blurred that readers shouldn't have to decide whether they're looking for documentation or for training. Sounds good. From personal experience, I'd throw troubleshooting, aka support, in there as well.
And we therefore put the boundaries back in for the same reason programmers came up with scripting languages, object-oriented programming languages, and tag libraries. The writers couldn't handle it.
Good documentation fills the gaps between what you're trying to do with the thing you're reading about, and what its exposed parts seem to let you do. But the exposed parts, sometimes known as the user interface, depend intimately on you, more than on the subject of the documentation.
For example, using a washing machine to clean laundry exposes parts that you model with abstractions like water temperature, spin speed, trays for detergent and fabric softener, start buttons, etc. Reparing a washing machine exposes belt drives, rotating drums, internal plumbing, etc. You can almost keep the distinctions clean there. Washing machines expose two nearly distinct user interfaces. Most writers, given a bit of understanding about washing machines, could information map out not only how you use a washing machine, but also how you troubleshoot it, and therefore everything you as a reader need to learn about it, unless you're the one doing R&D in washing machines.
Categorization gets murkier when you look at troubleshooting software. Interestingly, and although we writers try to pretend it's not so, the only time most of us return to documentation after we install software is to troubleshoot. Online training? Maybe it's taking off economically because it's subsidized by companies who somehow got sold on the idea as a cost-cutter. My experiences with online training have been uniformly disasterous. Troubleshooting with help from Google? Now there's something real.
But troubleshooting real software feels hard to do, let alone to understand enought to write about. What do you write when you realize that this blog entry is already far longer than anyone is willing to read, and yet even explaining the background needed to understand what can go wrong with multi-master directory server replication takes much more? You try to find good examples and hope they'll fit. (Another reason to expose you're *-interest mailing lists to Google.)
Hard work, even for an expert. Writers who try it may come back with just a FAQ and a bunch of good intentions, maybe a reference in Related Reading to Zen And The Art of Motorcycle Maintenance. So we categorize like writers, because we end up with writing we can do.
This is turning into an apology for Bryan Cantrill's 368 p., 1.3 MB DTrace guide, written by Solaris kernel hackers rather than somebody with a tech writer job title... Or the GNU make doc. If you want something written just for you, write it yourself.
The beta version of the DTrace doc incidentally has no occurrences of "trouble" according to Acrobat Reader.
Posted by Mark at July 9, 2004 07:47 AM