Much of my technical writing career has been spent as a contractor and consultant working with organizations that didn’t have technical documentation in place and need it in place fast. Throughout my travels, I’ve also spoken to even more project teams through the course of interviewing for potential projects. One thing I’ve learned is that Johnny can’t document a product may not always be the Johnny’s fault.

Creating technical documentation isn’t difficult nor does it require a select caste of individuals. A replicable process, some standards, maybe some templates, and oh yeah some common sense can help your technical documentation efforts go the distance.

Here are some reasons why Johnny can’t document a product:

Lack of standards

Even if you standardize on the Microsoft Style Guide for Technical Publications, Read Me First!, and/or a variety of other third party style guides available or take the leap and write your own style guide do know that having some styles and standards in place is going to help with the consistency of your technical documentation and help focus your editing and reviewing cycles. Even a set of simple standards scrawled on a yellow note pad can help prevent contradictions and settle some editor and reviewer comments.

Lack of project manager attention

Technical documentation doesn’t have to be an afterthought on a project plan though frequently end up as such. While project managers have enough on their plate, assigning the right technical writer to documentation tasks means the writer can do the heavy lifting for your technical documentation, not the programmers.

Lack of access

Cutting a technical writer out of the project equation entirely is another way to make creating technical documents a lot harder than it has to be.

An experienced technical writer with access to the product can be a lot more self-sufficient than a writer cut off from the product and solely dependent on programmer authored documents. Getting a technical writer access can save your development team a lot of time in the long run.

Inadequate staffing

You aren’t doing the overall project any favors by short changing the documentation elements. A senior technical writer with a seat at the table with the rest of the project team can take care of more documentation-related problems than they can cause.

Not setting up your documentation efforts for success can later overtake the entire project at an inconvenient time and the very least watching out for the issues in this post can save you at budget time.

Poor product management

The worst thing to ever happen to a technical writer is to ask a product manager a question about a product (supposedly their baby), and they can’t answer the question.

I’ve worked with the full range of product managers in my time including some that could speak to the nuances of their products, competitors, and markets to some who couldn’t answer questions from the development team or me as the technical writer.

Will Kelly is a technical writer and analyst based in the Washington, DC area. He has worked with commercial, federal, higher education, and publishing clients to develop technical and thought leadership content. His technology articles have been published by CNET TechRepublic, Government Computer News, Federal Computer Week, Toolbox.com, ZDNet.com and others. Follow Will on Twitter:@willkelly.

An earlier version of ths post appeared on willkelly.org on February 19, 2011

Image by Alejandro Escamilla via Unsplash.com