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

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:

• You can create consistency while you write.
• You can add it later, during the revision or editing stage.

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.

Create consistency while you write

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:

• Create a style guide for each project.
• Create a dynamic style guide.
• Create macros that do the repetitive work.
• Create automatic text shortcuts.

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.

Create a style guide for each project

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.

Create a dynamic 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:

• Most obviously, include the definitions of all paragraph and character styles that will be used by writers in the template.
• Add all standard headings, already typed, preformatted, and edited to perfection so that writers don’t need to type the heading text or apply the formats.
• Use all kinds of simple reminders (e.g., affordances), such as the instructions to “type the following five items here for each function”, followed by descriptions of the contents of those five items, already in the proper formats. Writers can simply select each line of text and type right over the top of it to provide the required information in the correct style, while simultaneously deleting the reminder.
• Include all boilerplate (recurring text) such as a copyright notice, legal disclaimer, and the publisher’s contact information so that this information doesn’t need to be retyped or edited.
• If possible with your software, store boilerplate information in a central repository and include the most recent version of the text automatically each time you open the document. (In Word, you can use the “IncludeText” field for this purpose.) This is particularly useful for writing teams, since this approach lets everyone benefit from this shared resource.
• Provide links to useful resources such as the corporate style guide, a glossary of key terms, and sample documents from which specific chunks of text can be emulated or can be copied and pasted into the current document. In Word, you can implement these links by inserting hyperlinks; that feature is under the Insert menu in versions of Word that have traditional menus, and in the Insert tab of the "ribbon" in versions that use the ribbon interface instead of menus. This feature lets you link to a Web page or to a document on your company's network.
• Set up custom toolbars that provide access to macros that have been written to make the writer’s life easier. In Word 2007, the old toolbars have been replaced with a single “Quick Access Toolbar”. (Chapter 4 of my book on onscreen editing contains information on how to create and customize such toolbars; the next section of this article and Chapter 11 of my book discuss macros.)

[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]

Create macros that do the repetitive work

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.

Create automatic text shortcuts

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:

• AutoCorrect is for short chunks of text (less than 256 characters) with fairly basic formatting. Word replaces the shortcut as soon as you press the spacebar or press Enter.
• AutoText (renamed “Quick Parts” in Word 2007 and 2010 for Windows) is for longer chunks of text, and can include multiple paragraphs containing complex nested paragraph and character style definitions. In older versions of Word, the software displays a popup balloon as soon as it thinks it’s guessed what shortcut you’re typing, and pressing Enter replaces the shortcut with the full text. In Word 2007 and 2010, this helpful hint has disappeared, and to make the feature work, you’ll need to press F3 as soon as you think you've typed enough text for Word to recognize the shortcut.

[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]

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:

• If every online help topic must have the same structure (e.g., subheadings for context, menu and icon locations, detailed steps, and cross-references), create a single AutoText entry named “]help” that contains all these headings plus hints below each heading about the required content.
• Phrases that you must retype frequently are good candidates for automatic text. For example, “Open the File menu and select” can become “]of” (memory aid: of = open file), whereas “Open the Tools menu, select Track Changes, then select” could become “]track”.
• Complex HTML, XML, or SGML tags such as <a href='URL' target='blank'> can easily become autotext. If you daisy chain two autocorrects (i.e., type the first one, insert any custom text, then type the second one), the first one will type the first part of that tag (<a href='), leaving the cursor in the right position to immediately type or paste the URL, and the second one will complete the tag (' target='blank'>).

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.

Add consistency during the revision or editing stage

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:

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:

• Type the text you want to use as a replacement, then cut it (Control+X in Windows, Command+X on the Mac) to move it to the clipboard. If that text is already present in the document, select it and copy it instead (Control+C in Windows, Command+C on the Mac).
• Select the word or phrase you want to find, and use the macro provided earlier in this section to find the next instance of the word. (Alternatively, copy and paste the word or phrase into the “find what” field of the search dialog box.) [A look back: Because of how that macro works, use the macro to find the search text before you copy or cut the replacement text. If you don't do that, you'll paste the search term into the document instead of the replacement text.--GH]
• Note that Word will highlight the text it found. If you need to replace that specific instance of the word, paste the text from the clipboard (Control+V in Windows, Command+V on the Mac) and it will replace the highlighted text.
• Move on to the next instance of the word using the “find next” keyboard shortcut: Control+PageDown in Windows, or Command+PageDown on the Mac. If you think you've missed one (e.g., you pressed the keyboard shortcut twice by mistake) and want to retrace your steps, use Control or Command plus PageUp instead of PageDown.
• Continue until you reach the end of the document. The search will wrap around to the top of the file and continue on to the point where you decided to begin the search.

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:

• EditTools
• PerfectIt

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.

Consistency is in your grasp

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.

Bibliography

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–2024 Geoffrey Hart. All rights reserved.