Every technical writer has been advised to understand the audience before documenting a product. Traditionally, this has meant understanding the needs of the product’s immediate users; however, you can’t always stop there. One user’s actions often have effects that involve many other people, 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. For many network managers, 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; however, 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 needed to do the work correctly. Sure, it means a little more overtime, but the freedom to work without interruption makes such times significantly more productive than if the network folks 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 you’ll be perfectly wrong. Many network managers, like one of my acquaintances, 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 they can restore the system to its working state quickly, with nobody ever being the wiser, and try again.
The opportunity 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 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.
© Hart, G.J. 2000. A different version of this article appeared as “Show some consideration when making network changes” in Computerworld Canada, February 11/2000:14.
