Technical writing: the step-child of IT?

technical writing logo

In my experience, technical writing alone of all the information technology functions is treated as a luxury. One large company for which I worked, for example, immediately eliminated the technical writing team whenever financial troubles loomed. Technical writing was considered “overhead” that did not directly contribute revenue; therefore, it was expendable.

This attitude has seemed nearly universal, at least in large companies. Only two conditions seem to make documentation a high priority.

1. Regulatory requirements

If a regulation requires documentation, it will be created. A number of people will want to have an imprint on the product. They will want their names listed as contributors, their points of view addressed and their concern for doing things properly noted.

After the document is written and the regulation satisfied, however, it is likely no one will ever read the document or direct anyone to do so, until something goes wrong. Then, the document will become the proof that someone - usually someone in the rank-and-file who is considered expendable - was at fault.

2. Downsizing and cost-cutting

When companies decide to eliminate jobs or lay off or replace personnel, the work those employees handled must be done by someone else. The tasks might be added to the workloads of remaining personnel, or they might be outsourced. In either case, documenting procedures becomes critical. I have even heard of companies penalizing outgoing personnel, via severance packages, who fail to train their replacements.

Read moreTeaser break marker


Why is technical writing undervalued?

One reason technical writing rates so low among IT skills is there are bad technical writers, just as there are bad programmers and bad managers, among the good ones.

Someone once told me the technical writer in his office thought her sole responsibility was to drop the developer’s text into the template and reformat it. My supervisor on one contract actually asked me to rewrite another technical writer’s work, because she simply could not understand it. On another job, someone said after working with me as the most recent of several technical writers, he finally understood that technical writers could be valuable assets.

Even if you put bad experiences aside, however, a number of fallacies about technical writing thrive.

Fallacy 1: Anyone can do it.

The ability to put words on paper - or a computer screen - and the ability to communicate effectively are two different things. Not everyone writes, or communicates, well, and not everyone writes all types of documents equally well. Communicating technical information accurately, concisely, completely in language appropriate to the intended audience is a specialized skill. The number of unintelligible user manuals in existence testifies to this truth. For detailed examples, compare the developer's and writer's versions of software installation instructions.

Fallacy 2: Hard-core technicians, such as the system administrators, programmers and engineers can write the documentation related to their jobs more easily than a technical writer.

This seems true until you consider that their perspective is that of experienced professionals instead of new hires. New hires, for example, may not know that the simple instruction to “take the system offline” actually involves three different steps - logging into a control panel, shutting down five different applications in a specific order and then powering down the server - instead of simply powering the server down with the applications still running.

Fallacy 3: Documentation is unnecessary if personnel know their jobs.

Again, this seems true until you think about the situation.

  • If there is no documentation, how can a novice cope with a rare but time-sensitive issue when the more experienced personnel are unavailable?
  • How can you ensure consistency in procedure when individual memory is the only guide?
  • How can you keep an organization running when critical knowledge disappears with a departing employee?

Fallacy 4: Hands-on training can substitute for documentation.

To some degree this can be true, but consider:

  • How much of your experienced personnel’s time can you afford to devote to training when there are complex issues only the experienced can handle?
  • How do you know the training is actually occurring? One technician once told me they could complete a task in less time than it would take to train someone else to do it. That is often true, but refusal to train lower-level employees is counter-productive to the team as well as detrimental to novice employees’ development.

End-of-file marker