Revising Documentation: Introduction

Revision and your documentation process

People outside the technical writing and directing game confuse revision with editing. Revision is, literally, “another look” at the first complete draft of a document (words, images, sound, video) to see that it facilitates the use of the thing being documented. Editing is a process that involves decisions at the sentence, image and frame (in video) levels that aligns the documentation with house style guidelines, clarifies sentence-level meanings and then prepares the documentation for final publication. (I regard “proofing” as the final stage of editing; others might not.)

Revision is a holistic reevaluation of the technical communications project—top to bottom. It requires going back the to the initial goals you set for the documentation project and seeing how well the draft matches your goals, which themselves may need some reworking at this point. For instance, what you thought could be accomplished by one piece of documentation, may be revealed as needing two separate documents.

Many times a good technical documentation revision will show that the tool or process being documented also needs another look. Once a representation of the tool or process is completed, it’s often apparent that the product is not delivering on certain explicit or implicit promises. Naming and interface design are two very common issues that arise if your revision is a thorough examination of how well the documentation matches the tool or process. Look at it this way: If the tool and the documentation fit “hand in glove,” you should make sure that the hand has five rather than four or six fingers.

Revision is so important to the quality of the final documentation that you should expect it to take as long as the initial draft, if not longer.

If your previously published documentation is being complained about, you need to find out why. Everybody knows that doing the same things and expecting different results is wrongheaded. Producing technical documentation is no different. Usually, problems in revising documentation fall into three broad areas: lack of information flow, writing/directing competence, and meddling by or a lack of inclusion of people whose functional responsibilities affect or will be affected by technical documentation.

Revision defines and resolves problems

The revision process should result in a user experience that works. If customers complain that your documentation confusing or incomplete, your revision process is the prime suspect. Revision should include tests of the drafted documentation and the tool it documents by people who don’t know much about  the tool or process you are documenting. Wherever reasonably intelligent people get stuck, that part of the documentation, or the tool, is not working.

It could be that your writer-directors are  “transplants” from the technical side of things, which means they could be assuming too much about their audience’s knowledge and skills. Writers aren’t trained to write code. Code writers aren’t trained to write documentation. It’s common that people coming over from the technical side take too much for granted about their audience.

If you are using professional writers, the drafted documentation might be missing technical detail. Very often, it’s difficult for writer-directors of technical documentation to have sufficient access to application or process developers (SMEs). If your company does have silos in the yard, these people are the most likely to reside in one. They’re not to blame—they’re creating the technology or solution you’re selling—but if you want your company’s products and services to produce a good user experience, tight collaboration between SMEs and writer-directors is essential to your success.

Revision also gives all concerned time judge the quality of writing that’s been done in the first draft. Although producing technical documentation in any media takes creativity, it is not an art form. So-called purple prose doesn’t fit technical documentation. Terms for particular functions/activities should be consistent. Problems in the quality of documentation come down to whether or not the people you employ or contract with to produce your documentation are actually good writers-directors. If you have high standards for the technical expertise you employ, you should have the same standards for writer.

Concision, completeness, correctness, clarity—your technical documentation needs these qualities. For instance, if your writers are failing to adhere to consistent editorial style, that is a fundamental problem. If they think varying the naming of elements and activities is good writing, that is also a problem. Varied diction (word choice) my be good journalism or novel writing, but it is death to documentation. If you have a particular function or activity that must be repeated to get from A to B, it’s important that it be called the same thing every time it is referred to. A click (or touch in a mobile application) is a click is a click. It’s also a problem if your documentation is uneven. That is, some sections are better than others. As a writer, I can spot pretty easily the sections of a document, series of images and video where your writer-director ran out of gas,  hurried through a topic, or didn’t really understand how things worked. Revision spots these inevitable ups and downs in a first draft and brings them up to snuff.

Finally, if you clicked the link to naming above, you’ll saw my analysis of how the Amazon shopping experience is sometimes misleading, primarily because a decision was made (whenever a decision is framed in the passive voice, beware!) by somebody to insist that telling people they are “shopping with Amazon” took precedence over the fact that they are in fact buying through a reseller rather than the seller in most Amazon transactions. Plainly speaking, this is an example meddling—if my conjecture is correct—in what should be an effort to show buyers exactly who they are buying from and who will be responsible for fulfilling their orders—from the start.

Also, documentation is closely linked to support and customer service. Are you including these people in the revision process. They can be especially helpful in defining where special emphasis or more development is needed in a first draft. They are also essential resources for creating FAQs for the tool or process. After all, deal on a daily basis with the problems your customers or employees are having with your tool or process. For this reason, they are your best source for developing FAQs and clarifying where “bottlenecks” occur.

Revision and your documentation tool/media

So many companies think that the first part of documentation is to decide on the documentation tool and media. This is backwards. You should choose the tool  according to the needs revealed in revision. If you company is already “locked in” to a particular tool, you should not expect different results from using the same tool. It’s ideal that your tool be flexible in its ability to employ the various ways of publishing copy (hard copy, tool tips and lightboxs), voiceover, images (within the document narrative, in light boxes, in slide banks) and video.

Tagged with: ,
Posted in Technical Documentation

Leave a Reply

Your email address will not be published. Required fields are marked *


* Copy This Password *

* Type Or Paste Password Here *

%d bloggers like this: