This is absolutely a rant, triggered by an observation on Twitter by Allen Holub, in which he noted,
“I should add that the Guide provides an object lesson for any software shop that thinks that they don’t need an on-staff technical writer. Do you really want the written material you produce to look this bad? Doesn’t say good things about your company.”
I am in violent agreement on the horrible results so many companies encounter when they dispense with tech writers – and yet, in my experience, most tech writers don’t do an awful lot more than basic copy editing. They fix misspellings, obvious grammatical errors, and so on, but since they don’t understand the technical material, they frequently don’t recognize the kinds of problems Alan is pointing out. What we actually need from technical writers is guidance in how to organize and present the material, not simply how to write clean sentences.
That’s not to say that there isn’t a lot of value in that, but it’s just a start. A larger problem tends to be the whole idea of how to present material so that a user can understand it. It isn’t all that easy, and the results of not doing so can be very costly, not only in the perception of the company who publishes such work, but in the increased support required to field questions from confused customers. When prodded, Alan cited the following example from the Scrum guide:
“The Increment is the sum of all the Product Backlog items completed during a Sprint and the value of the increments of all previous Sprints.”
There isn’t really a lot wrong with the grammar or spelling, here, and many tech writers might not flag it in the first draft from an engineer, but it’s also pretty worthless. Maybe, as he suggests, a copy editor would have flagged it. My experience with tech writers doesn’t give me a lot of confidence.
I have had a very good experience with a tech writer, once. It was early in my career, and he was a much older writer. Rather than having me write a user manual for some software I had written, he interviewed me. He asked me to teach him how to use the product. Then he wrote the manual and had me check it for correctness. It took a lot more of his time, and maybe more of mine, but it produced a much more usable document.
And we need this, not only for user docs, but for specifications. Just think of how much time is lost by engineers trying to read what comes out of spec-writing committee. If you think code without tests is bad, think of code without tests written by somebody who had no access to anyone who actually knew the requirements. Tech writing is one of those key skills that so many companies don’t seem to understand doesn’t come automatically to engineers, along with spec writing and both creating and presenting technical information. I should probably not rant about watching most PowerPoint slide shows