You are here: Articles --> 2012 --> Creating consistency while you write—or adding it later
Vous êtes ici : Essais --> 2012 --> Creating consistency while you write—or adding it later
By Geoff Hart
Previously published as: Hart, G. 2012. Create technical writing consistency while you write—or add it later. <http://techwhirl.com/articles/create-technical-writing-consistency/>
[A look back: The Techwhirl version of this article differed from this version in two major respects. First, most references to writing were expressed as references to "technical" writing. I've deleted the "technical" here where it wasn't crucial because the article really applies to all forms of writing. Second, Connie Giordano, my editor at Techwhirl, did a great job of coming up with screenshots. I haven't included the screenshots here, so click the link at the start of this article to see Connie's screenshots.--Geoff]
One of the primary tasks any writer or editor must perform is to impose consistency on a manuscript. Consistency is particularly important for technical writers, because it makes the task of writing easier: if you don’t have to develop a new solution each time you face the same problem, you can simply find a solution that works for all occurrences of that problem and use it consistently thereafter. The more often you use that solution, the more automatic it becomes and the faster you become at using it. That’s much more efficient than the alternative. But consistency is also important for readers: once you’ve proven to them that you’re a reliable guide to solving their problems through clear explanations, and that you don’t make careless mistakes, readers tend to assume that any inconsistency is intentional and that it conveys a new meaning. If the inconsistency is just carelessness, you’ve both wasted their time and undermined their faith in the rest of your writing. [A look back: Five ways that consistency matters provides more justification for this opinion.--HG]
From the writer’s perspective, it’s best if you try to build in that consistency right from the start, because it can save you a lot of time both in your initial draft and in your subsequent revisions. If you’re fortunate enough to be working with an editor, you can rely on that person to help you be more consistent, but the more consistent you are right from the start, the more of that editor’s attention remains that can be brought to bear on more significant problems such as logic and clarity. You’re also saving time for the editor, and if you’re in a typical workplace, writers greatly outnumber editors and the editor’s time is in high demand. Even if you’re working on your own, being consistent makes it easier to revise your own work.
Whether you’re a writer, an editor, or someone who plays both roles, you can achieve consistency in two main ways:
Both are valid strategies, but the first one is arguably more important because it increases both your efficiency when you create the information and the subsequent efficiency of editing or revision. In the rest of this article, I’ll teach you about some of the tools you can use to make your writing more consistent during both the creation and the revision phases.
As I noted earlier, an important reason to strive for consistency is that it spares you the need to constantly rethink the solution to recurring writing challenges. You can accomplish this in several ways:
Most of my description of the technology will be based on recent versions of Microsoft Word, but comparable solutions exist for most other word processors and desktop publishing software.
In simplistic terms, a style guide represents a repository of wisdom about proven strategies for solving specific kinds of language problems. Complex disciplines such as software and hardware development, scientific research, and engineering have their own specialized style guides, and these are great resources as reference material while you’re learning the style conventions of a discipline and the logic behind these decisions. Working primarily as an editor, I have a handful of style guides in my office that are suitable for different kinds of editing, and I consult them frequently.
But most writers and editors find that their specific niche within a larger discipline such as software development raises certain problems that aren’t covered in even the most ambitious style guide for that discipline. Thus, it’s necessary to create a smaller, more highly customized guide that deals with the exceptions and gaps in those larger style guides. The value of such a project-specific guide increases when multiple writers are cooperating on a larger project, since imposing consistency on a group of writers who work without such support can be a thorny problem for the poor editor who’s responsible for imposing a single consistent voice, vocabulary, style, and feel to the writing. Chapter 9 of my book on onscreen editing provides some useful advice on how to create and use such a custom style guide.
The problem with most style guides is that they’re a resource that is external to the work of writing and revising, and like traditional online help, they are therefore not integrated with the task. Like any other form of user assistance, using them takes you “out of the task”; that is, you have to stop writing or editing, find the guide, find the relevant topic, and return to your writing. As a result, only the editor usually bothers to memorize and use the style guide, and most writers only consult it when they’re truly lost and need help solving a problem; the rest of the time, they’re happy to leave consistency to the editor. The solution is to integrate the style guide, as much as possible, directly within the writing process, and the easiest way to do that is to create a unique kind of template that I refer to as a “dynamic style guide”. In my article on dynamic style guides, I provide details of the following suggestions for creating a dynamic style guide:
[A look back: Needless to say, someone still has to review all manuscripts produced using a template, whether or not the template is dynamic. You'd be amazed at how easy it is to forget to remove reminders while writing, and how often even a highly evolved and polished template contains bits and pieces that aren't relevant for a specific manuscript or missing bits that such a manuscript requires.--GH]
One of the great advantages of computers is how they let us automate repetitive work that doesn’t require much in the way of brainpower. In Microsoft Word, this automation is performed using “macros”, and in other programs by using “scripts”; both represent a prerecorded (or programmed from scratch) series of instructions that ask the software to perform a list of tasks. In the context of consistency, a macro can control the word processor’s search and replace tools and use them to perform a long series of word or phrase replacements. For example, if you have a list of deprecated words that must be replaced with a corresponding list of preferred words, you can record a simple macro that performs one of these search and replace operations for a specific word pair, then edit the macro so that it covers additional word pairs. To do so, all you need to do is copy and paste the text that describes a single specific search and replace operation, then edit it to work for a new word pair. Chapter 11 of my book on onscreen editing provides a more detailed explanation, and some sample macro code you can use. However, if you do this kind of thing a lot, you’re better off purchasing Jack Lyon’s Megareplacer software. Megareplacer automates most of this kind of task, and provides a host of other useful tools.
Another typical macro might involve cleanup to fix the most common kinds of problems. These include inadvertently typing double spaces between words; leaving a space at the start or end of a paragraph; numbering items in a list manually instead of using an automatic numbering feature; changing the language used by the spellchecker from (say) U.K. English to U.S. English; aligning equations with the left margin instead of indenting them; and so on. Any pattern that you can define in the search and replace dialog box can be included in the macro. You’d be amazed at just how sophisticated Word’s search and replace function can be; consult Jack Lyon’s free guide to search and replace to learn the details. Jack Lyon also recently published his “macro cookbook” for Word, which will entertainingly and quickly teach you everything you need to know about macros.
One of my favorite Word features is its suite of automatic text features, which let you type a shortcut and automatically replace it with a much longer text. These come in two main flavors:
[A look back: There's a reason that autocorrect features have spawned the derogatory name "auto co-wrecks": particularly on smartphones, it's easy to not notice the software has automatically corrected what you've typed in a variety of unfortunate ways. My tip in the following table about prefacing your shortcuts with a recurring character, such as "]", will help you avoid this problem.--GH]
To create AutoCorrect text and shortcuts:
Word 2007/2010 for Windows
Word 2008/2011 for Macintosh
To create AutoText (Quick Parts) text and shortcuts in Word 2007/2010:
Editing and deleting Quick Parts in Word 2007/2010:
As an editor, I’ve created a few dozen of these shortcuts, which together save me more than an hour per week that I would otherwise spend repeatedly typing several recurring editorial comments to communicate with my authors. As a writer, you can create these shortcuts for any recurring pattern of text that you have to write. Here are three simple examples of the possibilities:
Paying attention to the kinds of things you need to type repeatedly will give you a long list of standard phrases that should become automatic text. A colleague who works at the United Nations, and who is required to repeatedly create documents containing a mixture of myriad chunks of standardized text, told me that he has created more than 250 of these shortcuts. Using them judiciously lets him create a complex, customized multi-page document in minutes (versus hours for some longer variants of these documents) simply by typing the right shortcuts in the right order.
Best of all, if each of these shortcuts has been carefully edited, little or no additional editing will be required. Any editing is usually limited to the inevitable small adjustments that are required when a specific chunk of standardized text doesn’t perfectly fit the context for the current document. Chapter 11 of my book on onscreen editing contains additional suggestions on how to use these tools. It’s worth noting that if you’re part of a group of writers or editors who must all type exactly the same phrases, sharing your shortcuts with the rest of the group will also improve their writing and editing efficiency.
Many of the tools described in the previous section are also useful for editors, but editors need a different suite of tools for many recurring editorial functions. Many of these rely on the find and replace feature. For example, if you want to scan through a document and find every instance of a particular word to see whether it’s being used correctly, you’ll need to open the find dialog box, type the word, press the “Find next” button, then close the dialog box every time you need to do this search for a given word. It’s far more efficient to create a macro that does this for you. Because this specific macro can’t be recorded due to a limitation in Word, I’ve provided the text here so you can copy it and paste it into the macro editor:
| Macro for finding selected word
' FindSelectedText Macro
' Macro recorded 10/5/07 by Geoff Hart
' Define selection as variable
MyFoundText$ = Selection
.Text = MyFoundText$
.Replacement.Text = ""
.Forward = True
.Wrap = wdFindAsk
.Format = False
.MatchCase = False
.MatchWholeWord = False
.MatchWildcards = False
.MatchSoundsLike = False
.MatchAllWordForms = False
To use the macro, all you need to do is select the word or phrase that you want to search for, then press the keystroke that runs this macro to search for the selected word. I use the keyboard shortcut Control+Alt+F in both the Windows and Macintosh versions of Word.
For large-scale word replacements throughout a document, you can use the “global” find and replace feature. (Here, “global” means “throughout the document”.) For example, you can use this approach to replace each member in a list of deprecated words with the preferred word. However, although this works well in documents that have a narrow and tightly controlled vocabulary (e.g., in a book that contains examples of XML code), global search and replace isn’t safe in documents where the text is more diverse. In that case, there are likely to be enough exceptions to the list of deprecated words that you need to examine each instance to decide whether a replacement is necessary. Here’s an efficient technique that lets you do this directly from the keyboard:
Note that although you can do this kind of task from directly within the search and replace dialog (by typing the replacement text in the “replace with” field and clicking the “Replace” button each time you need to replace the selected word or phrase), that approach is far less flexible. Not only does the dialog box often obscure the document window, making it difficult to see the surrounding context that will tell you whether a replacement is necessary, but it also limits the replacement text you can use; in the dialog box, the replacement text has severely limited formatting (e.g., you can’t boldface the first word and italicize the second word or apply character styles to either word). Also, if you need to do more than replace the word (e.g., you want to insert a comment to ask the author to confirm whether the change should be made), you need to close the dialog box, make that change, then reopen the dialog box to continue your search.
Chapter 8 of my book on onscreen editing provides a range of other useful tips on how to use the find and replace features to impose consistency on a document. If you have unusually complex needs, and you want to automate your work instead of doing this kind of manual labor, there are two powerful tools that are worth investigating:
Both tools let you create word lists and rules that the software will then use to confirm that an author has been consistent. Although you can use the tips I’ve provided in this article to do this work manually, you’ll find these tools a better choice for long documents and collections of documents by multiple authors.
Technical writing involves many repetitive tasks that can affect the consistency of an entire document. Pay attention to the things you do repeatedly as you write or revise a document, and you’ll find many other examples of how to use the approaches described in this article to increase your consistency. Not only will you produce a more consistent document; you’ll work faster, leaving more time to deal with more interesting and challenging communication problems.
Hart, G.J. 2000. The style guide is dead: long live the dynamic style guide! Intercom, March:12–17.
Hart, G. 2010. Effective onscreen editing: new tools for an old profession. 2nd ed. Diaskeuasis Publishing, Pointe-Claire, Que. Printed version, 507 p.; eBook in PDF format, 723 p.
Lyon, J. (no date) Advanced find and replace for Word.
Lyon, J. 2011. Macro cookbook for Microsoft Word. The Editorium, Salt Lake City, UT. 106 p.
©2004–2018 Geoffrey Hart. All rights reserved