Document Hack (A Technical Writer’s Journal): The Sinking Ship is in Beta

At this point in my career I have read about twenty different books on technical writing, and few of them seem to address the real job. They tend to portray technical writing in an idealized world in which the writer is a valued part of every step in the process — from planning to the first draft to rewrites, editing and the finished product. Sometimes a writer gets the opportunity to follow documents through the entire process, but as a document hack (contract technical writer) I seldom get that luxury. The closest analogy I can find to what I do is to jump onto a sinking ship and start trying to patch the holes before the ship goes under.

I owe much of my career to poor planning and a lack of cooperation. Not on my part (my personal limitations are another issue) but on the part of the large corporations I work for. My current assignment is a good example. I have been brought in to rework documents created by a system rife with both poor planning and poor cooperation.

The first problem is that engineers were assigned to be the primary writers. The problem with this is that engineers are trained to work in a technical field but are not trained to provide technical information. Explaining information so that it is useful and understandable really is not their jobs. More importantly, writing these documents is not a priority with the engineers; documentation is a job they are assigned to do in addition to their primary jobs.

The second problem is that these engineers are not well-trained in the documentation development platform. FrameMaker is a powerful desktop publishing tool aimed at technical communication and long document creation. It is not a simple tool, at least when compared to a traditional word processor such as Microsoft Word.

The engineers at this company are given only cursory FrameMaker training and no training in writing. These engineers are expected to funnel their knowledge of diverse parts of the system into a one-size-fits-all boilerplate document. Because of the complexity of FrameMaker and the poor training the engineers receive, they often alter the required formats and styles, even when they try to adhere to them.

The third problem is that the boilerplate itself is poorly planned. The engineers often make unauthorized changes to the boilerplate because it does not fit their needs, and there is no set system for dealing with these changes.

You would expect a department that is putting together 8000 pages of documentation on a product to take the time to hammer out exactly what they want the document to achieve. Instead, the boilerplate document was created ad-hoc. One person took a crack at it and sent it out to the engineers. Midway through the process, another person decided to completely change it. There was little to no consultation on this. In the end, the boilerplate the engineers followed (if they bothered to follow it) turned out to be unusable and a third boilerplate was created after the engineers had turned in their work.

This is where I come in. My job is to take these original documents (which may have been created with boilerplate one or boilerplate two) and make them fit boilerplate three (which is still being altered). The documents have to be out in a few weeks, and the original engineers/authors have moved on to another project and cannot be consulted. Their time is too valuable. I must make my best guess about where everything goes. When there are problems, there is a great deal of confusion about who to go to for solutions.

I would like to point out again that this company is no better or worse than the majority of my clients. The situation is pretty normal. I walk in amidst chaos and I try my best to create something that makes sense. I would like to say I am a miracle worker and that these documents somehow get transformed into useful and valuable materials, but I am a document hack, not a miracle worker. I do what I can and then I move on.

My first priority is to get the documents out. My second priority is to improve them as much as I can in the time that I have them. Often, documents are overdue by the time I am even hired for the job.

The technical writers who are employed by the company are constantly trying to improve the process and educate the engineers and managers on what needs to be done. Unfortunately, they have made little progress. Because I am a contractor and not an employee, I worry only about doing the best job I can under the constraints given. It is not my job to fix the system.

The central issue in the technical writing field is that documentation is not a priority at most companies. That is something a prospective technical writer needs to understand. Companies with an intelligent and well executed documentation process are the exception, not the rule.

Related links

• The Technical Writing FAQ (0.500)
• Technical Writing Part Two: What a Technical Writer Writes (0.500)
• Technical Writing Part Three: A Technical Writer's Skill Set (0.500)
• Technical Writing Part Four: Desktop Publishing Tools (0.500)
• Technical Writing Part Five: Education (0.500)