Jan 2006 Newsletter
Good Practice
10 Tips for Editing Your Own Technical Writing
by Victoria (Viki) Maki
Although I have been a technical author for more than a decade, I am still humbled by the difficulty of editing and proofreading my own writing. And, as a senior-level contract technical writer, I am often in the position of being the lone writer on the team, and consequently, I am forced to edit my own work. In this article, I share some of the tips I have found most useful in editing my own writing. While these tips apply especially to technical writing, they are useful for editing any kind of writing.
1. Make Multiple Passes
Technical documents are inherently complex. Not only do they contain text that must be edited, but they also have headers, footers, tables, graphics of various kinds, and other diverse page elements, all of which must be edited and checked. The only effective remedy I have found to manage this is to make multiple passes through a document, addressing specific issues with each pass.
This is nothing new. Copyeditors usually make multiple passes, starting with a read-through of a manuscript to evaluate content, organization, and any special problems they have to address. Typically though, an experienced copyeditor may make only two passes through a manuscript before giving it back to the author. Why is this not enough for a technical edit? As I mentioned earlier, technical documents are visually complex, with numerous page elements, such as tables, lists, graphics, etc. No one can address all these elements in one pass. This article specifically addresses editing and proofreading your own writing, so presumably, you are familiar with the content and organization of a piece you wrote. The challenge of the first read-through of your own work is to distance yourself. To edit to best advantage, you must treat your work like someone else’s writing. This means that you are past the stage where you read your words aloud and shake your head in amazement at your own talent. You’ve taken off your super-hero costume and are ready to don the rumpled fedora of a hard-boiled editor, grimly determined to find every error. Presumably, also, you did an initial outline, so the overall document organization is adequate. Given this, you can do a first read-through that focuses on content issues you may have overlooked as you wrote, such as paragraph organization. Does each paragraph develop fully one main idea? No irrelevant sentences? Good transitions? Inevitably, you’ll see some other glaring errors, such as a header that wasn’t updated, and you can feel free to mark these problems, also.
Now that you’ve addressed content and corrected obvious errors, you’re ready for organized subsequent passes based on the unique character of the document. Do you have complex graphics? Devote a pass entirely to them. What about tons of bulleted lists? Consider making a pass where you do nothing but examine the terminal punctuation for the list items to ensure it is consistent, based on the style you adopted for the lists. The beauty of the multi-pass editing approach for technical documents is that you can examine as little or as much in each pass as you like. Just remember to keep going until you proofread and find no errors. 2. Proofread Character by Character
Your eye and your brain, unfortunately, are conspiring against you when it comes to your own writing. Errors obvious to someone else (particularly those like “the the”) escape you. There is nothing to do but accept this and deal with it. One of the most powerful techniques I have found is to proofread character by character, rather than word by word. I typically print a hard copy of the document, sit down in a comfortable chair under a good, strong light, and patiently read each character. When my discipline flags and I start reading word by word instead, I invariably find I overlook errors. 3. Use Tricks to Freshen Your Eye
Every experienced technical editor has her favorite trick to get a fresh perspective on a document. Here are some of the ones I’ve heard over the years:
There is a school of thought among technical authors that argues that a writer can’t effectively edit her own work, because she will inevitably have blind spots. While I think another set of eyes is always valuable, I do believe an experienced writer can edit and proofread her own work effectively, particularly if she knows her own weaknesses.
Knowing your own weaknesses need not involve intense soul-searching; it’s as simple as making a list of the words you commonly look up. In addition, as you edit your own work, look for reoccurring weak grammatical constructions. For example, do you habitually use the passive voice, even though you know it is usually not preferred in technical writing? What about not having a clear antecedent for pronouns? You knew what you meant by “it,” now didn’t you? 5. Always Create a Style Sheet
Even if your style sheet is only a word usage list on the back of an envelope, it’s better than nothing. It is essential that you keep track of your style decisions for at least words in transition (website) and terms used inconsistently (San Andreas Fault versus San Andreas fault, for example).
A style sheet typically captures a number of editorial decisions concerning:
I think most of the technical documentation that gets produced would benefit by extra time in the schedule, so that it could be edited once more with a fresh eye. I think that the typical problems one sees—inconsistencies in capitalization, punctuation, and terminology, as well as other problems, such as wordiness—would be apparent, if only the writers and editors could step back from the document long enough to see it fresh. 7. Allow One More Tiny Pass
Even if you can’t build in two days of “wiggle room,” consider allowing enough time so that you can make one more focused pass in which you perform “editorial triage.” That is, you look for what you suspect are the most serious remaining problems in the document and fix them. 8. Expect to Make Errors
When you review your technical writing, expect to find errors until you have combed through the document numerous times, proofreading character by character where time permits, and using your favorite tricks to produce a pristine document. 9. Be Passionate about Small Things
In my experience, most technical authors and editors are passionate about grammar, good writing, and all matters great and small that are relevant to quality technical documentation. I remember a spirited discussion in 1992 about whether “database” should be written as one word or two. (At that point, the word was in transition from “data base” to the form “database” that is commonly seen today.) All the members of the technical publications department where I was a contractor approached this discussion with relish and a great deal of feeling. In my experience, good writers and editors care deeply about such matters. We have to, as we are the ones responsible for maintaining writing and editing standards. 10. Build a Good Reference Library
A good reference library is an essential investment for any serious writer or editor. Here are some of the books I consult on a regular basis. STYLE GUIDES
The style guides you use are determined by the niche you occupy as a writer. The style guides listed below are standard for a technical publications department producing technical documentation
Technical documents are inherently complex. Not only do they contain text that must be edited, but they also have headers, footers, tables, graphics of various kinds, and other diverse page elements, all of which must be edited and checked. The only effective remedy I have found to manage this is to make multiple passes through a document, addressing specific issues with each pass.
This is nothing new. Copyeditors usually make multiple passes, starting with a read-through of a manuscript to evaluate content, organization, and any special problems they have to address. Typically though, an experienced copyeditor may make only two passes through a manuscript before giving it back to the author. Why is this not enough for a technical edit? As I mentioned earlier, technical documents are visually complex, with numerous page elements, such as tables, lists, graphics, etc. No one can address all these elements in one pass. This article specifically addresses editing and proofreading your own writing, so presumably, you are familiar with the content and organization of a piece you wrote. The challenge of the first read-through of your own work is to distance yourself. To edit to best advantage, you must treat your work like someone else’s writing. This means that you are past the stage where you read your words aloud and shake your head in amazement at your own talent. You’ve taken off your super-hero costume and are ready to don the rumpled fedora of a hard-boiled editor, grimly determined to find every error. Presumably, also, you did an initial outline, so the overall document organization is adequate. Given this, you can do a first read-through that focuses on content issues you may have overlooked as you wrote, such as paragraph organization. Does each paragraph develop fully one main idea? No irrelevant sentences? Good transitions? Inevitably, you’ll see some other glaring errors, such as a header that wasn’t updated, and you can feel free to mark these problems, also.
Now that you’ve addressed content and corrected obvious errors, you’re ready for organized subsequent passes based on the unique character of the document. Do you have complex graphics? Devote a pass entirely to them. What about tons of bulleted lists? Consider making a pass where you do nothing but examine the terminal punctuation for the list items to ensure it is consistent, based on the style you adopted for the lists. The beauty of the multi-pass editing approach for technical documents is that you can examine as little or as much in each pass as you like. Just remember to keep going until you proofread and find no errors. 2. Proofread Character by Character
Your eye and your brain, unfortunately, are conspiring against you when it comes to your own writing. Errors obvious to someone else (particularly those like “the the”) escape you. There is nothing to do but accept this and deal with it. One of the most powerful techniques I have found is to proofread character by character, rather than word by word. I typically print a hard copy of the document, sit down in a comfortable chair under a good, strong light, and patiently read each character. When my discipline flags and I start reading word by word instead, I invariably find I overlook errors. 3. Use Tricks to Freshen Your Eye
Every experienced technical editor has her favorite trick to get a fresh perspective on a document. Here are some of the ones I’ve heard over the years:
- Turn the document upside down. Start from the end and read backwards, going line by line. Zoom in to 200 percent or more, particularly to edit graphics. Zoom out until you can see the entire page to edit overall page elements, such as the space before and after headings.
- Read aloud to both slow yourself down and to catch errors you’ve overlooked reading silently.
Create a PDF of your document and proofread that.
There is a school of thought among technical authors that argues that a writer can’t effectively edit her own work, because she will inevitably have blind spots. While I think another set of eyes is always valuable, I do believe an experienced writer can edit and proofread her own work effectively, particularly if she knows her own weaknesses.
Knowing your own weaknesses need not involve intense soul-searching; it’s as simple as making a list of the words you commonly look up. In addition, as you edit your own work, look for reoccurring weak grammatical constructions. For example, do you habitually use the passive voice, even though you know it is usually not preferred in technical writing? What about not having a clear antecedent for pronouns? You knew what you meant by “it,” now didn’t you? 5. Always Create a Style Sheet
Even if your style sheet is only a word usage list on the back of an envelope, it’s better than nothing. It is essential that you keep track of your style decisions for at least words in transition (website) and terms used inconsistently (San Andreas Fault versus San Andreas fault, for example).
A style sheet typically captures a number of editorial decisions concerning:
- Acronyms and abbreviations Capitalization Formatting and page elementsNumbers and datesPunctuation Terminology and trademarks
- Word usage
I think most of the technical documentation that gets produced would benefit by extra time in the schedule, so that it could be edited once more with a fresh eye. I think that the typical problems one sees—inconsistencies in capitalization, punctuation, and terminology, as well as other problems, such as wordiness—would be apparent, if only the writers and editors could step back from the document long enough to see it fresh. 7. Allow One More Tiny Pass
Even if you can’t build in two days of “wiggle room,” consider allowing enough time so that you can make one more focused pass in which you perform “editorial triage.” That is, you look for what you suspect are the most serious remaining problems in the document and fix them. 8. Expect to Make Errors
When you review your technical writing, expect to find errors until you have combed through the document numerous times, proofreading character by character where time permits, and using your favorite tricks to produce a pristine document. 9. Be Passionate about Small Things
In my experience, most technical authors and editors are passionate about grammar, good writing, and all matters great and small that are relevant to quality technical documentation. I remember a spirited discussion in 1992 about whether “database” should be written as one word or two. (At that point, the word was in transition from “data base” to the form “database” that is commonly seen today.) All the members of the technical publications department where I was a contractor approached this discussion with relish and a great deal of feeling. In my experience, good writers and editors care deeply about such matters. We have to, as we are the ones responsible for maintaining writing and editing standards. 10. Build a Good Reference Library
A good reference library is an essential investment for any serious writer or editor. Here are some of the books I consult on a regular basis. STYLE GUIDES
The style guides you use are determined by the niche you occupy as a writer. The style guides listed below are standard for a technical publications department producing technical documentation
- The Chicago Manual of Style, 15th edition, The University of Chicago Press, 2003.Microsoft Manual of Style for Technical Publications, Microsoft Press, 2003.
- Read Me First! A Style Guide for the Computer Industry, edited by Sun Technical Publications, Prentice Hall, 2003.
- Merriam-Webster’s Collegiate Dictionary, 11th Edition, 2003. The Copyeditor’s Handbook by Amy Einsohn, University of California Press, 2000.
- The Deluxe Transitive Vampire (and other grammar books) by Karen Elizabeth Gordon, Pantheon Books, 1993.
- The Oxford Style Manual, Oxford University Press, 2003, ISBN 0-19-8605641
- The Oxford Dictionary of English, Second Edition, Oxford University Press, 2003, ISBN 0-19-8613474
- The Economist Style Guide, 2000, ISBN 1 86197 209 1 Practical English Usage, Michael Swan, Oxford University Press, 1995,
ISBN 0 19 431197 X - Eats, Shoots and Leaves, Lynne Truss, 2003, ISBN 1-86197-612-7