Discussion on:

Tips for managing the technical documentation tech review

title is longer than the point of this article?

As a Technical Writer, I am fully aware of the need for the technical accuracy of a document, and the development team needs to be a part of that process -- like it or not. Even the best Tech Writer cannot read the mind of a developer. Even with thebest technical specification to work from, the best TW needs to confirm they have interpreted it correctly.

Lorin

From my experience...concerning the time it takes to meet, explain, review, meet, discuss, explain, review, over and over to a Technical Writer, I can write it myself in half the time.

The amount of time it takes to create a technically correct and user targeted document is considerable. The amount of training it takes to enable technical writers to deal with this type of attitude from what is, typically a junior, or immature developer is comparable. "A1Nut" is likely the product of an environment that simply does not understand the job of a technical writer. Team leaders, supervisors and managers, I urge you, pay attention to your team members, and when you detect an "A1Nut"type evolving, take a good hard look at why they have that attitude. Education is the key to a fully integrated, smooth cross-functional process. This guys attitude is costing some poor sap a lot of time and money. As for you, yourself, "A1" don't underestimate your business peers. Since you have a problem with your tech writers and their process, don't whine about it, fix it. You would be surprised how much you could achieve with a bit of constructive critism towards these folks.
jmac

you can write it but will anyone else be able to understand it.

I would strongly disagree with the point that Technical Writers are a waste.

The basic idea of using a person who does not see things from developer's perspective for writing the technical documentation is to present the information to a non-technical person as simple as possible.

Therefore the role of the Technical Writer is to put himself in the position of the end user and try to cope with the developer's point of view at the same time.

Take a developer and make him write the User Guide. Question is if another developer will be able to use it, not to mention the end users.

One way to ensure the technical accuracy of documentation is to have one place where source information is kept up-to-date. This is called Single Sourcing -- once the source information is created or updated, the information or changes are propagated to all documents.

This increases accuracy and reduces the numer of technical reviews to one. Once reviewed, the Tech Writer sends the information or updates to the affected documents without changing the source information in the process.

THE RESULT

Technical reviewers only need to do one review of the source information -- they don't have to review every document (i.e., the online help, user guides, training materials, marketing materials, etc.).

Technical Writers don't have tore-write the source information because it is already in the format needed for the deliverables -- write once, use often. They also don't have to chase developers around (bake fewer brownies) to get the technical review done.

Lorin