Editing Technical and User Documentation

As technical writers, most of us get a chance to review documents prepared by colleagues or writers from other teams. While a few may be reluctant to do reviews, it is a fact that the reviews provide technical writers with an opportunity to participate in the quality control process of user and technical documentation.

If the team has a technical editor, he or she may be left with enough time to do a thorough review of documents. A process will be in place to plan and complete editing. If one of the team members take up the taks of editing, the edits mostly will be a mix of “copy-editing” and “technical editing". A“production edit” can also be done on the draft versions of the PDFs created to ensure that everything is all right before it is send to the customer. The limiting factor indeed is time.

The first step in editing is to read the entire document once. It is indeed a quick read just to get an idea of what is it all about. Such a reading does give me an idea about what can possibly be the editing effort required and the complexity of the edit. On most occasions, I have been successful in marking one or more glaring issues.

In the second phase, start reading the document word by word and line by line. I begin by marking the typical copy-editing stuff using the track changes in Word or FrameMaker or as sticky notes or comments in Acrobat Professional, or even in emails. The copy-editing errors looked into include spelling, grammar, punctuation, usage, style, and writing consistency. I tread carefully on spelling mistakes because I do not want to miss spelling errors borne out of a mix of English styles such as UK English and US. I put comments as well as suggestions where the usage, grammar, and punctuation used are mixed up. For example, a comma before the conjunction “and” in a list.

Other issues focused include the voice and the tense used. Paragraphs often have sentences written in active and passive voices. I often feel that some sentences look better in passive voice, rather than in active voice. I keep an eye on sentences that suddenly shift tenses from the present to the past and even to the future for unknown reasons. I also ensure that the author follow a consistent style across the document, including the capitalization used, the terminology used, the length of sentences, and so on. Sentence construction is always a tricky issue. Paragraphs are checked to ensure that multiple ideas are not stacked, but spread out in multiple paragraphs.

Beyond copy editing, I specifically look for sentences that are technical, speak the SME's language and not the user's languages, filled with jargon, and ambiguous. The technical nature of the text and badly constructed sentences create lots of cruft. The result is the user finds it difficult to comprehend the meaning and the idea. A documentation bug is the result in such a scenario.

In other cases, there is less focus on context, but more on procedural tasks. As a result, the reader will not know what a particular feature is about, why he or she should do it, and what exactly can be achieved. Clearing these issues, at times, involve talking to the author or referring to documents such as requirement specs and design documents. In such documents, I put suggestions to rewrite the paragraphs or sentences for clarity. Compromise is the mantra.

At times, another strategy employed has worked wonders while editing. This is to log in to the application and match the procedures in the documents with the application (I know this will not work for complex software and hardware). Such a strategy helps me in ensuring whether crucial elements or steps of the work flow are missing from the documentation. It can be a field, a menu, a drop-down item, or buttons, or a shortcuts, related tasks, and so on. A technical editor can also look into issues such as the mismatch in documenting the names of GUI elements, dissimilarity between the screenshots and procedures, screen names, the tab flow of fields (if present), mandatory values, lack of troubleshooting tips, and so on.

I also look into the template issues, formatting, and layout. Currently, this involves correct use of character and paragraph tags and master pages, heading styles and hierarchy. On PDFs, I also check whether cross-references work and whether they land on the page intended. I do comment on the overall layout: topics starting at the end of the page, orphan sentences and bulleted lists, and pages starting with screenshots and notes and warnings, procedures without intros. I also check the white space present in pages and the proportion of body text and graphics on a particular page so that the “weight” is balanced.

I like words and like to review definitions of terms. While a few can be verified using the internet, on many instances, I need to discuss them with the authors as well as the experts.

I check the organization of the document. Instead of topics organized to relate to each other, topics may look disparate and incoherent. They may lack unity among various sections of the document. It simply means the whole will not be the sum of its parts. Typically, I will try to ensure that writers do not miss the crucial aspect of ensuring a flow so that the information is rendered not usable. If a casual reader cannot find the information easily, imagine the plight of the user who is busy to finish the task. I love cross-references in te documents. I feel the absence of adequate cross references thwarts the unity of the document.  If I enter a few details, I should know how to verify that information. Documentation and its architecture sometimes miss this crucial element.

Finally, I just close the document and come back to it later to review my comments. I do this to ensure that I have missed anything and I have not done any hyper-editing.

For me, copy-editing or technical editing is not nitpicking. It is not an act to put someone on the defensive. It is a quality control process to ensure delivery of good and quality documentation to customers. It is also a learning process for me, as I need to be first sure that my concerns are right, and my findings are valid. It is not necessarily that I am always right. The author can also be right and I can learn from him or her. It is a collaborative process to ensure that the efforts fulfill the wider objectives set for.