Print This Post
| 
Email This Post
Category: Technical Writing.
Yesterday’s Salt Lake Tribune featured an article that relates to technical writing in an intersting way.
Apparently last October there was an incident at Hill Air Force Base, where a mechanic made a mistake that caused over six million dollars in damage to an aircraft’s engine. (The plane in question apparently costs over $200 million.)
A contributing factor was deemed to be a lack of proper documentation for removing landing gear pins after performing maintenance on the plane.
Here is a quote from the article:
“Investigators concluded that, while Air Force guides correctly instructed Raptor mechanics to install the landing gear pins before performing maintenance on the airplanes, there were no similar step-by-step instructions to ensure mechanics remember to take the pins out prior to clearing the aircraft for use. “
Who says documentation isn’t important? Way too often people talk about how expensive documentation is, and how there isn’t a visible return on investment for the money spent in the documentation department. I think a better question is “How expensive would it be to not document our product properly?”
Good documentation is about more than just helping people turn on their computers, although that is certainly part of it. Good process documentation thinks outside the box to consider how people will actually use your product, and then giving them the information they need to use it correctly.
Recently on the Techwr-L list there was a discussion about boring documentation. The general complaint was that documentation is too boring; most people don’t pick it up and read it for fun. There is some truth to that. However, I think one of the posters had it right when he said that you have to first consider both your audience and the product that you are documenting. If you are documenting a web search program or if you are documenting a computer game, it is probably okay to use a conversational tone. However, if you are documenting procedures that are potentially dangerous or whose repercussions could be serious, it is best to be more formal, and border on the side of too many cautions and warnings.
In the case of the airplane mechanic at Hill AFB, the lack of proper procedural documentation ruined a six-million dollar aircraft engine. Somebody assumed that because there was a documented procedure in place for placing the pin, that the end user would automatically know how to remove it safely. If a proper procedure had been established, and followed, this mistake likely wouldn’t have occurred. The mechanic probably wouldn’t have taken the procedure manual home for some light weekend reading, but that wouldn’t have been the point of this particular procedure.
There is a lot involved in creating good documentation. You must understand and write to your audience. You have to think like your consumer, and include necessary steps to help accomplish reasonable use cases (including considering alternative use cases where your users don’t see what to you seems obvious). Then you have to produce a product that meets the needs of your users.
This process can be difficult, and it can be expensive. But the alternative can be worse, and can cost a lot more.
