Editing, Writing, and Translation

Home Services Books Articles Resources Fiction Contact me Français

You are here: Articles --> 2001 --> The needs of the many
Vous êtes ici : Essais --> 2001 --> The needs of the many

The needs of the many

by Geoff Hart

Previously published as: Hart, G.J. 2001. The needs of the many. <>

Every technical writer has been advised to understand their audience before they begin documenting a product. Traditionally, this has always meant understanding the needs of the product’s immediate users, and although that’s certainly important information, you can’t always stop there; that one user’s actions often has effects that involve many others beyond the immediate user of the product. Understanding the human environment in which your audience works has important implications for how you write. Consider the not-so-carefree life of network managers and their staff, for instance.

Among all the other crises that enter the life of people responsible for networks, installing hardware or software upgrades ranks right up there with paying taxes in terms of stress. One of the more familiar sights from my days of hanging around the MIS department was that of the network staff doing laps around the building in January at –40C, chain-smoking and wondering how long they could keep from freezing solid before they had to return to the building’s warmth and start the next round of installations.

Why so much stress? Well, first, there’s the instinctive fear of screwing up something that’s already working "reasonably well, thank you very much”, and spending the next 60-hour week trying to get back to where they were before they “improved” things. That’s a scary prospect even for those who enjoy living on the bleeding edge and installing all the new software they can find on their home PCs. After all, it’s comparatively easy to reformat a single hard drive and reinstall the former software, but in the workplace, an entire corporation worth of users is waiting to discover even the slightest mistake and set up a wailing that will be heard in Redmond (Washington)—or that would be heard if Microsoft actually listened to the users of its products. Think of it this way: how often do major software developers release completely bug-free upgrades?

This makes it fairly obvious that installations and upgrades should be done on evenings or weekends, even if that messes with the installer’s home life. Working outside regular business hours provides the peace and quiet computer people need to do the work correctly. Sure, it means a little more overtime, but the freedom to work uninterrupted makes them an order of magnitude more productive than if they had to hide from their daily business of lost passwords, crashed computers, and missing e-mail. Rushing through upgrades under these conditions guarantees errors, and fixing the damage is going to cost them more home time than doing the upgrades outside the regular work day.

That being the case, it’s hard to imagine that anyone would do otherwise, and if you’re documenting the installation procedures for a networked product, it’s perfectly reasonable to assume that the network gnomes will do just that—and perfectly wrong. Many network managers, like one of my acquaintance, insist on doing installations during regular business hours so they won’t interrupt their home life and so they’ll have access to the local computer emergency consultants if they need to be bailed out. That’s all very well, but whenever an installation fails to work the way it should, everyone on the network loses an hour or more of work until the cavalry arrives to fix things.

As the person responsible for the documentation that the installer is going to rely on during the installation, don’t you have a responsibility to point out the side-effects of such decisions on the hidden audience of network users? Of course. Being a user’s advocate is all about thinking through all the consequences for the audiences you serve, including the hidden audiences that lie one step beyond the immediate and obvious audience of users of your product.

Given the strong temptation to take the seemingly easy way out and do the installations during regular hours, how can you dissuade readers from doing so? By making a compelling case for the advantages of working while nobody else is around. When you write the contextual information that often appears in the Getting Started or Read Me First portions of the documentation, point out the benefits of creating the best possible impression with the senior managers and other workers who depend on the installation being done right—and who will complain bitterly if things go astray. When things do go wrong—and it’s almost axiomatic that something will go wrong, some time—the only person who’ll be truly inconvenienced by work done outside regular office hours is the installer. Of course, if you concede the possibility of error, then you should recommend that installers keep a disk image (backup copy) of the server tucked away somewhere safe so that if something goes wrong, they can restore the system to its working state quickly, with nobody ever being the wiser, and try again.

The opportunities to gain the reputation of being a true wizard who never brings down the network and to curry favor with the folks who determine the network manager’s salary next year is an awfully compelling incentive, not to mention the gratitude of the community of network users who see the beneficial effects of the installation without ever feeling its adverse impacts. An hour lost fixing a problem during working hours doesn’t seem so serious until you realize it amounts to 500 worker-hours worth of time for a mid-sized company. You can bet someone’s going to notice that much lost time, and if 500 of those someones all get bent out of shape, you can bet that management is going to have a few words to say about it. Let’s not let the poor installer go there.

Sometimes being self-sacrificing really isn’t all that noble after all. It just takes a user’s advocate to point this out.

©2004–2018 Geoffrey Hart. All rights reserved