A lot 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 organizations through the course of interviewing for potential projects. One thing I’ve learned is that Johnny can’t document a product.
Creating technical documentation isn’t rocket science nor does it require a select caste of individuals. A replicable process, some standards, maybe some templates, and oh yeah some common sense can really help your technical documentation efforts go the distance.
While some of the reasons why Johnny can’t document a product, these issues can sneak up an ultimately sabotage a documentation effort and ultimately the entire project.
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 PMs have enough on their plate, assigning the right technical writer to documentation tasks means the writer can do the heavy lifting.
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. A good 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 technical team a lot of time in the long run.
Inadequate Staffing. Parking your weak performers on technical writing tasks can put your technical documentation efforts on the road to ruin. You aren’t doing the overall project any favors by short changing the documentation elements. A strong technical writer with a seat at the table with the rest of the project team can take care of more problems than they can cause.
Not setting up your documentation efforts for success can later overtake the entire project at an inopportune time and at the very least watching out for the issues in this post can save you at budget time.
Graphic by Stock.xchng user: stevenafc
About Will Kelly