Technical Writing: Editing and Reviews

Dallas-Fort-Worth (DFW) Texas based Brandfocal Consulting provides Branding, Search Engine Optimization (SEO), Content Management and Technical Writing services.


You might think the process of technical writing is complete once you put the last word on the page, but it isn’t. Every document needs to be reviewed and edited. In some cases, you’ll be fortunate enough to have an actual editor in place to edit your document, but most technical writers must rely on another technical writer or even do it themselves. In addition to the normal editing tasks of checking grammar, general word usage, and spelling, technical editing includes several other elements including checks for consistent word usage, checks that a consistent audience is maintained, and checks that the organizational choices make sense.

Reviewing often occurs at the same time as the editing process but it serves a very different purpose. While editing ensures a clean grammatically correct document with consistent style, it doesn’t test the accuracy of the content in any way. Reviewing does. If possible, you should have at least one of the developers who wrote the product participate in a review as well as at least one person who fits the target audience profile. If the person within the target audience doesn’t understand everything you wrote then even if it’s accurate you haven’t successfully met your mandate and need to re-write the document accordingly. If the developer finds inaccuracies or points out areas where the product was changed then similarly you need to fix those before declaring the document finished.

Working with an editor

If you work in a large organization, chances are you’ll have one or two editors who need to sign off on your documentation before its published. These editors check your books for spelling mistakes, incorrect grammar, flow, and other general common writing problems. They also check for proper use of trademarks, adherence to the corporate style, consistency, widow and orphan lines, pagination issues, and other features that might be specific to your particular company or department.

You might think proper grammar provides a concrete set of rules that leave no room for interpretation but that’s not the case. The hardest part of working with different editors is that each has his or her own slightly different interpretation of the rules. The rules regarding commas, for instance, are flexible. I’ve worked with editors who saw commas as the enemy and eliminated as many as humanly possible without altering the meaning and I’ve worked with people who prefer to include commas every single instance it’s possible to do so. Both are correct – it’s all a matter of preferred style. Until you learn the style of a new editor expect some growing pains.

The single most important thing to remember when working with editors is that they do not, in general, understand the subject matter of the books they’re editing. They do, at times, unwittingly suggest changes that alter your meaning. It is your responsibility to go back to the editor and point this out. Just because an editor requested a specific change does not automatically mean you must make it. If it’s a bad change in your opinion, discuss it with the editor and explain why you feel your way is better. Any editor worth their salt will sacrifice their rules or strictly correct grammar for accuracy. 

Peer editing

Smaller groups often don’t have any editors but rather institute peer editing. Once your book is finished (or once specific sections are finished) you give them to another writer in the group for critique. Again, the main purpose is to ensure correct spelling, correct grammar, and adherence to the group style. In some cases, the writer editing your work will know nothing about its subject but in others, the writer may indeed know the product quite well. In those cases, you’ll most likely get comments on the content in addition to actual editing. This amounts to an extra reviewer and content-related comments should be treated as review feedback.

Peer editing is usually an informal process leaving you the option to integrate or ignore the results as you see fit. It’s less like to catch small errors or minor deviations from the accepted style than a formal edit. Writers have varying experience with editing and sometimes the best writers are not the best editors. If you work in a group for a long time you’ll get a feel for who the better editors are and, hopefully, be able to give them your books for editing. 

Self-editing

If you work alone, work as a contractor, or sometimes if you’re in a small group there isn’t anyone else available to edit your work so you have to do it yourself. Editing your own work is very difficult because you know what you’re trying to say. You have extra context clues and background to fill in any blanks that might actually be in the writing so it’s easy to miss mistakes or omissions.

If at all possible, leave some time between the completion of the writing and the beginning of your editing process. This gives your brain some time to forget exact word patterns and helps you catch more problems with the writing. If you can, it’s best to work on another project in between the writing and editing steps.

Reading your work out loud can be a very effective self-editing tool. Your brain is less likely to fill in missing words if you’re trying to vocalize them. Any awkwardness or odd pauses in the writing are also more apparent when read out loud.

Why reviews are important

Technical writers get their information in a number of different ways. Many software products are described in specification documents well before their first line of code is written. These documents serve as a starting point for everyone working on the product – developers, technical writers, and testers alike. Often cross-functional teams have ongoing meetings to access progress and discuss changes to the product. Developers, product managers, and other involved parties send emails back and forth containing product information and suggestions.

As a technical writer, it’s your job to be a fly on the wall at as many of these conversations as possible. Get yourself on every email list you can. Get invited to those boring meetings. If you’re lucky, you can also be an early alpha or beta tester of the product and see how it works first hand.

Even if you get a constant stream of emails, go to three meetings every week, and get the chance to use the product to your heart’s content, there will be last-minute changes to the product. There may be earlier changes that you don’t know about or that never came up in any of the meetings. Some developers may not be forthcoming with changes or your product manager may forget that you need to know a particular piece of information. Even if you have all of the information, you may have misinterpreted something or not fully understood everything you read or heard. The review process is a check built into the documentation process to catch all of those omissions and changes and mistakes. 

Dealing with difficult reviewers

Some people are more cooperative than others. It’s a fact of life. As a technical writer, you need to deal with a lot of people who don’t necessarily see helping you as part of their job description (even when it should be). Some people will be very forthcoming when you ask them questions, others will practically need to be tied down before they answer you. Similarly, when sending material for review, some people will comply and give you the necessary feedback in a timely manner while others won’t.

If a particular developer isn’t cooperating with a review request, notify your manager and ask for his or her help. They may suggest you discuss the obstruction with the reviewer’s boss or have other suggestions to elicit cooperation. If you can, find an alternate source of information – if a developer isn’t cooperating perhaps the person testing those features or a consultant using them will.

Ultimately as long as you tried to get your material reviewed, it’s not your fault if there are technical inaccuracies. Unfortunately, this doesn’t help the customers getting confused by the mistakes so you should make every effort to get the needed feedback. 

Integrating review comments

At the end of a review cycle, you’ll most likely have several sets of feedback on the same material. Sometimes the comments will conflict, sometimes they may not make sense. More often than you’d like they’ll point out deficiencies and missing information. You can also get off the wall review comments or run into a reviewer who feels it important to correct the grammar and writing style of your book, often doing so without checking the technical content. As with the editing process, when it gets right down to it, you are in charge of the document and you decide which comments are helpful and need to be addressed in the documentation before it’s released.

Corrections can generally be made within a few days, barring long discussion of conflicting comments, but vital information that simply isn’t documented cannot usually be added so quickly. If your release date is nearing and a reviewer insists that a new chapter is needed, you may not have time to research and write this new information. At that point, it’s your responsibility to inform the product manager of the request to add more information and explain that it cannot be completed within the current schedule. He or she can then determine whether the projected completion date is strict or if you can have more time to add new information. It is unlikely that the product release date will be altered just so you can add more documentation (although it has happened to me twice) so this determination will generally be based on the current state of the product itself.

If you make extensive changes after the first round of reviews, you may want to ask for another round of feedback from your reviewers. At the very least, you should send the changed sections to the reviewers who suggested the changes so they can sign off on the modified information.

Which comes first – Reviewing or Editing?

In general, editors like to be the last person to see a book before it’s released. If you have actual editors chances are you’ll want to go through the review process before the editing process.

Alternately, if you’re fairly confident that there won’t be massive changes needed after the review, you could propose simultaneous review and edit periods. You could then offer the finalized, post-review document to the editors for a brief final edit to ensure you didn’t violate standards when you integrated the review comments if that would make them more comfortable. I like this approach as it gives me the chance to integrate all requested changes at once rather than having to go back and forth multiple times with different people making a handful of changes each time.

If you’re using peer or especially self-editing, I recommend editing before the review process. That ensures other eyes have seen the document after your edits and gives you another little check in the process.