A long time ago in a job far, far away, I rose to the position of Engineering Manager, but one of my core functions until the day the company collapsed was proof-reading documentation produced by my fellow engineers and consultants. As a computer science graduate who had spent pretty much every free elective in senior high school and university doing the arts, I had a passion for well written documentation.
The next company I worked for did not share my passion for documentation. Spell check was something witches used, formatting errors were a form of post-modern expressionism-cum-document decoration, and the semi-colon had murdered and usurped the role of its cousin, the colon. After eight years in the role I’d managed to convince one or two colleagues that semi-colon and colon were not interchangeable, but the victories beyond that were few and far between. I maintain to this day I was in the right, and for one simple reason: I regularly watch non-technical users become entirely perplexed by poorly written documentation, and even technical users who happen to not be domain experts in a particular product become befuddled by bad documentation.
Anyone can write. Writing in such a way that comprehensible and accurate information is imparted to the reader is a talent less cultivated within IT, and I think that’s a serious flaw with how IT works.
If you’ve ever been referred to a medical specialist by your GP, you know there’s invariably two types. There’s the specialist who is truly knowledgeable about his or her field, but more importantly, is an adept translator: they can take complex medical information and bring it down into lay-terms that leave you informed and confident that you understand. Then there’s the other type, the specialist who is far more interested in demonstrating a high IQ and employs very little tact or compassion to do so.
Working in IT isn’t just about the technology, it’s about making the technology accessible to others. The first way to achieve this is following the design adage as simple as possible but no simpler. A good smart phone for instance doesn’t need to come with a user manual because its interface should be simple enough that someone can learn it, or at least learn a significant amount of it with little to no cognitive processing.
The second way to make technology accessible is by providing instructions. Depending on how the product is used, that might be video-based – a recorded demonstration may achieve considerably more than documented steps, particularly if it’s something particularly visual. Apple’s Trackpad System Preferences under Mac OS X is a good example of this:
Each option in the Trackpad preferences is accompanied by a short video – literally no more than 5 seconds each, yet one that demonstrates the hand/finger movements required to achieve the control gesture. Just as a picture may speak a thousand words, a video demonstration adroitly sidesteps a textual description of a gesture, and equally neatly avoids having to make such information available in dozens or more languages.
IKEA, equally, have been masters of the visual instructions. Their simple diagramming style has allowed millions of customers around the world assemble hundreds of millions of pieces of flat-pack furniture with just a few pages of highly visual instructions.
When pictures or videos aren’t an option however, and instructional text must be used, then we must think very carefully about who might read that text. This places an obligation, a moral imperative on the writer to:
- Be accurate.
- Be honest.
- Be brief.
- Be consistent.
Accuracy is achieved by producing documentation whilst walking through the steps being described, and faithfully noting all the steps taken. For example, consider the average installation Wizard. On Windows you might see an installer start with the following sequence:
- Start with a language selector.
- Display introductory information while initialising.
- Launch into a preamble giving a short explanation of the product and offering a “Next” button.
- Presents a dialogue where the user chooses from a variety of installation options.
In my experience, at least 7 out of 10 documents produced in the IT industry to describe a sequence such as the above will start at item #4. A small few might suggest the user needs to move past each of steps 1-3, but an even smaller few will actually describe that process to the user.
That’s not dishonest, but it’s certainly not accurate.
Dishonest documentation is technically inaccurate as well, but it goes a step further. Most of us have seen it at one time or another – documentation that talks about options that aren’t in a dialogue, a menu that isn’t present, or a feature described in generic documentation not available in the particular model we bought. For instance, documentation for an installation utility for all that god-awful software that comes with most consumer external hard drives might tell you that you can choose to install:
- Some awful backup utility.
- Some awful encryption utility.
- Some awful media browser.
But what it fails to tell you is that on this particular version of the installer, the encryption utility wasn’t provided, so the documentation describes a dialogue box option that isn’t present. Or maybe you can choose the backup utility or the encryption utility, but not both, and the documentation doesn’t mention that at all.
I recently had a conversation with a quite intelligent friend and lawyer about a hard drive utility installer much like I described above. Used to a certain precision in his documentation, he was thrown by the installer not offering him the options described in the accompanying text. When the hard drive he bought wasn’t working (for an entirely unrelated reason), his first thought was that he must have done something wrong.
No: the documentation was just dishonest.
Brevity is the life of the party. Brief, concise documentation allows the reader to scan through quickly. Brevity comes after accuracy and honesty. Note that: you should be as brief as possible, but no briefer. There is no point cutting required information out of documentation if the result is inaccurate or dishonest documentation.
Finally, consistency is about running with the same terminology throughout the entire document – and ensuring it’s the same terminology used in the actual product as well. It doesn’t matter that an experienced user will understand that you mean the same thing if you use the terms folder and directory interchangeably. Consider the inexperienced user instead. (Think of those sorts of conversations you’ve had with an older relative who becomes perplexed at the difference between clicking a button and hitting a button.)
Beyond accuracy, honesty, brevity and consistency, there’s one other guiding principle you should be following when working on technical documentation, but this one is for yourself, not any potential reader, and that’s pride. Take pride in what you do. Don’t see documentation as some dreaded obligation, but a chance to make a difference. Ultimately it doesn’t matter how good your product is if you fail to communicate that to the person who purchases or even wants to purchase it.
Technical documentation, good technical documentation needs to be more than an afterthought in IT. Those who are so apathetic towards writing good documentation themselves are often derisive of poorly written documentation coming from other parties. Well, pot meet kettle, as the old saying goes. Documentation doesn’t have to be perfect, but the more readily you align your writing style to those four core factors, the better it will be … and in doing so, you’ll have done a good thing.