Geeks With Blogs

Technical Writing by Mark Metcalfe, Publications Professional

Your technical writer has completed a 20-page draft of a feature that your team has been working on and sends the team a notice for review, allowing for a week to review it and make comments. You put it on a pile somewhere with a vague intention to skim through it before the next project team meeting. When the meeting arrives, you approve the documentation by your silence, relying on the expertise of the writer because the document never left your growing Inbox.

This is not uncommon. Reviews of documentation are very hard to come by, and when they do come, they are usually done by a very few conscientious persons; usually the primary developer and a technical editor (if your company is lucky enough to still employ them). Documentation reviews often are missed by people with specialized perspectives such as people in customer support, pre-sales, training, and quality assurance. As a writer, I know all the reasons and excuses (and some of them very legitimate), and I have accommodated many reviewers by extending review deadlines (often with meager results).

Aside: I will observe here that there is an inverse ratio of the cost of the software product and how accurate and complete the documentation needs to be at release time. If you sell a product inexpensively, then your razor-thin profit margins cannot afford the expenses of customer calls or inadequate documentation. Conversely, if you sell a very high-end product, you can send a product expert to hold the hand of the bleeding-edge customer who is willing to pay for the advanced versions of the software (while the documentation department continues to create content in preparation for the mass adopters of the product).

It is usually true that the more experienced writer on a project can mean that you can risk not reviewing the documentation – but in these economically difficult times, companies are more likely looking at costs rather than value, which means looking for lower cost alternatives - so weigh your risks before ignoring that review. Getting it right the first time saves money in the long run.

If the Ghost of Past Reviews visits you in the middle of the night, telling you that every customer call against faulty documentation is a new link in a ponderous chain, and you’ve said to yourself that the documentation is the business of the technical writer, permit me to shriek and moan and rattle some chains to remark that “Documentation is YOUR Business!” In the same way that the technical writer reviews and comments on software - offering usability suggestions to make the software better - other cross-functional members of the team have a stake in the documentation because it affects the perception about the quality of the product. Every member of the team is responsible for the output of every other member of the team, or all you have is a collection of talented but disconnected individuals.

Mark Metcalfe

Posted on Wednesday, July 15, 2009 9:52 AM | Back to top

Comments on this post: Documentation is YOUR Business

No comments posted yet.
Your comment:
 (will show your gravatar)

Copyright © TechnicalWriting | Powered by: