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.
5 comments:
Great post. I love the line, "the more writing you do, often the worse the end product becomes." So true. We believe that every word we add to our documentation makes it less likely that someone will read it. Every sentence needs to add value.
Great post.
I think the slices of that pie may iffer, depending on the type of documentation you are doing. But I hesitate to argue with Andrew, as he is one of the finest writers I have known. I think he is describing the process of writing documentation for a new software product.
But for other types of technical writing (e.g., capturing amd articulating engineering
plans and strategies, RFIs, RFPs, technical marketing, etc.), as well as the circumstances -- your mileage may vary.
For example, if you are working from good, relatively well-writen specs, investigation time goes down. If you are working with bickering subject matter experts, you have to spot the disagreements and reconcile them. I try to get the experts into a room together (no small feat) and let them argue it out.
I also think that 20% writing time is a bit low. I often write early drafts for distribution for the experts to throw rocks at. I've even made stuff up from whole cloth. Once, after encountering a particulary cryptic section in a spec, I wrote such a piece of fiction and distributed it to engineering. Soon the lead programmer charged into my office
and yelled said, "Where the hell do you get this stuff?"
Fortunately another developer popped up from a nearby cubicle and
said, "You know, that wouldn't be such a bad way to implement it."
Also, the pie chart doesn't have a slice for removing the barbs you so often get from developers. You just have to have a thick skin, and make it known that you'd rather have correct documentation
than an unbruised ego.
And you have to have a sense of humor. Once our entire writing group was called to a meeting, but Andrew and I stayed at our desks because we had a lot of work to do. They came and got us.
There we learned that we had won an STC award of Distinction for
"BASIC for Beginners" and "More BASIC for beginners. I thought that was pretty cool, until we learned that we were beaten out for
first prize by a manual called "Getting To Know Your Tractor."
Talk about coming down to earth...
Cheers,
JP
John's absolutely right. I was thinking of new product documentation when I wrote my post. As the saying goes "your mileage may vary" depending upon the nature of the project and the completeness of the planning.
But I must confess, I haven't seen a decent functional spec in over 15 years. And agile development tends to make this situation worse, from the writer's perspective.
I am not saying this is bad -- many bad products came from overly strict and untested UI specifications. But I suspect an equal amount of spurious product implementations come from SCRUMs with insufficient time allowed for usability and testing.
In the end, it is not the process, or even the percentages, that define the usefulness of the end product or its associated information, but its connectedness to the gestalt of the business it supports and the people who will use it.
Lois Wakeman sent me the following comment via email:
"You and I know that, but many clients (especially developers) think the more words the better, and convincing them that brevity is best is often an uphill struggle. Knowing what to leave out is as important as understanding what to put in.
If we were paid by the page, I could see their point I suppose. ‘Never mind the quality, feel the width’. ”
Post a Comment