Tuesday, October 5, 2010

The Work of Technical Documentation

Contrary to the assumptions of many, the job of technical writing doesn't involve that much writing. The actual act of writing is at most 30% of the work.

In fact, the more writing you do, often the worse the end product becomes. Writing is a test of understanding. As you write, you come to realize what it is you understand and what you don't.

But if your job is to write, you not only need to write to understand, you need to write to be understood. Two distinct and at times opposite goals.

The danger is that, when writing instructions for something you don't completely understand, you write more. You try to write around the parts you don't understand; you describe it two or three times in the hope one of the descriptions sparks understanding in the reader; or you simply transliterate what you are told, because you can't figure out what parts are important and what parts aren't.

The result is lengthy documentation that does more to obfuscate that elucidate.

So if technical writers don't write, what what is it that they do? Well, primarily we investigate. We learn so we can explain. This is particularly true of new products where often the developers themselves don't know exactly how the features will be used by the customers.

I lay no claim to scientific accuracy, but my estimate is that more than half of the time technical writers spend is used in investigating. Of the remaining time, about half is used for actually writing. The remainder is used for testing (to see that what we wrote is true) and "production" (proofreading, editing, and the tedious and finicky work of tweaking the content into the appropriate output).

Are there exceptions to this "rule"? Yes.

  • New Projects: When you are starting a new project from scratch, excessive amounts of time are dedicated to production, since you need to get your processes and tools right. Then the split is more like 40% investigation, 20% writing, 10% testing, and 30% production.
  • Wrong Tools: If you aren't using structured tools (for example. using Word instead of xml or other structured tagging system), you spend far more time on production but don't know it because it is indistinguishable from the writing. At least 30% is production and/or rework spread out across the project at all times.
  • Updating Existing Documentation: If you are doing an "update", less time is spent on investigation but it is usually made up for by more time in testing as you need to make sure existing descriptions are still accurate. Something like 40% investigation, 25% writing, 25% testing, 10% production.