|
–Geoff-Hart.com: Editing, Writing, and Translation —Home —Services —Books —Articles —Resources —Fiction —Contact me —Français |
You are here: Articles --> 2000 --> The style guide is “dead”: long live the dynamic style guide!
Vous êtes ici : Essais --> 2000 --> The style guide is “dead”: long live the dynamic style guide!
by Geoff Hart
Previously published, in a different form, as: Hart, G.J. 2000. The style guide is dead: long live the dynamic style guide! Intercom, March:12–17.
Nobody, least of all an editor like me, would argue that printed style guides are really dead—at least not in the sense that they’re no longer with us and no longer useful. Yet there’s no doubt that printed style guides are looking a little antiquated these days. Despite how useful the guides are to writers and editors, they’re simply too static for most writers, and don’t take advantage of computer technology to make the writer’s working life easier. But if you’re thinking that online style guides are inherently better solutions, think again; using the computer to find static information certainly helps, but simply moving a paper guide online only exchanges one form of “static” for another.
So what’s the solution? Make the guide dynamic. That is, emphasize the “guide” part of the name and figure out how a style guide can actually guide writers in doing their work. This article points the way, but first, a little refresher course: what is a style guide?
Consistency improves any organization’s communications because it ensures that everyone speaks with the same voice and uses the same language; ideally, the process of seeking consistency also ensures a high and consistent degree of quality and clarity. Although “elegant variation” (using synonyms and fancy language for the sake of variety) provides essential color and texture in creative writing, technical communicators generally avoid this form of elegance because popular consensus holds that such variation risks confusing less-sophisticated readers.
Style guides fill the gap between the need for consistency and the means of being consistent, provided that someone’s available to enforce the guidelines. For the purposes of this article, I’ve assumed that it’s your organization’s editors who will impose consistency on communication and improve the quality of that communication, but for all practical purposes, you can treat “editor” as my shorthand for anyone, including managers, peer reviewers, and external reviewers, who will review documents for conformity with the style guide.
Well-designed style guides serve as important reference tools that contain well-organized, effective solutions for recurring problems. Guides provide these solutions in the same way that dictionaries do: they can follow a descriptive philosophy and report how writers actually use words, or a proscriptive philosophy that describes how writers misuse words and which usage patterns are forbidden. The best style guides adopt a mixture of both approaches: they proscribe approaches that experience has shown to be counterproductive and provide (prescribe) alternatives where two or more equally valid solutions exist.
Dozens of style guides already sit on bookstore and library shelves, so why would anyone bother creating yet another one? That’s not an idle question; a typical style guide for a complex subject easily fills hundreds of pages, and proposing to build something that large by yourself takes a certain amount of arrogance, tenacity, and optimism (not to mention staff resources). But unless you’re writing for a subject area that has already been well-defined by an existing style guide, such as the guide used by a peer-reviewed scientific journal or university press, it’s unlikely that any commercial guide covers all the topics you’ll need to cover. Every organization has different communication needs, and even when a comprehensive published guide covers 90% of those needs adequately, other resources must cover the remaining 10%.
Most of that 10% involves unique types of communication problems that arise only in your organization’s specific forms of communication. No writer other than someone intimately familiar with these problems can solve them for you. These problems also represent the 10% you need to make dynamic, and that I’ll emphasize in this article. And because the problems are unique to your organization, I’ll deal with the approach to making the solutions dynamic, rather than addressing specific problems.
I’ve said that a printed or online style guide is static, and that means the guide just sits there as a reference tool. There’s nothing wrong with that, but by taking advantage of the power of the computer, you can expand the guide to encompass the tools your authors use to write, and integrate it within the processes your organization uses to produce its communication (whether in print or online). That’s what makes the guide dynamic.
To create a dynamic style guide, you’ll need to discover and focus on the key issues for your writers. That means you’ll need to start by identifying the main types of communication your organization performs: these may be technical reports, data sheets, user manuals, marketing materials, business letters, online help, Web pages, or even speeches and presentations. Some problems will be common to all these products, whereas other products may be sufficiently complex that they require their own style guides. For example, the nature of the communication products that my current employer creates led me to develop separate guides for writing our reports and for creating our graphics and presentations.
The thousands of pages in an unabridged dictionary reveal that English is formidably complex simply because of its size: the sheer number of words available to be misused is mind-boggling. Worse yet, the most popular printed style guides each take hundreds of pages to describe the rules for using all those words. It’s obvious that you can’t cover every possible topic unless you’re willing to somehow recapitulate those thousands of pages, but fortunately there’s a simpler solution: don’t do it! Just as you wouldn’t reinvent the dictionary when you create a printed (static) style guide, you shouldn’t do so in creating a dynamic style guide.
Of the dozens of style guides already available, one or more will meet most of your general needs, and you should take advantage of that resource. In most case, simply pick an existing style guide that appears to be highly relevant to your industry and start working from that. Most style guides use this approach themselves; for example, they eliminate the need to include an entire dictionary with a simple statement such as “except for the few words we cover in Appendix A, consult [dictionary name] for all spelling and usage issues”. To help you find an appropriate style guide, have a look at John Renish’s excellent bibliography of technical communication resources (listed in the references section).
Now that you’ve picked a good static guide, you can ignore all the issues it covers and focus on those that it doesn’t cover. Some of these issues may still need to remain static, at least until you can figure out how to integrate them transparently with the way people work. I’ll cover how to make solutions into dynamic, integrated tools in the following sections; here, I’ll describe how to identify the types of things that can be made dynamic.
As in any other technical communication project, you need to start with knowledge of your audience (i.e., you need to do an audience analysis). In this case, your audience includes all the writers who create each type of communication product; these are the people who can help you develop a list of the most serious and frequent problems they face within their daily workflow, and these are the problems you should try to solve first.
For example, most general-purpose style guides don’t address the needs of the people you’re actually writing for; if you’ve chosen an appropriate guide, it may mention these needs, but because the authors didn’t know your actual audience, they couldn’t possibly focus their guide on those needs as well as you can. Information gleaned from usability tests, audience analysis, technical support databases, and training staff will focus your attention on the aspects of style with the greatest payback in terms of customer satisfaction. Your editors, marketers, technical-support staff, and trainers can provide valuable input on the types of problem customers spend a lot of time fixing; they can also provide important advice on the kinds of things writers must do to satisfy your own internal audiences (e.g., management reviewers). Ask managers, peer reviewers, and anyone else who approves your communication products to identify the problems they face. Speak to the writers themselves to find out what questions they waste the most time trying to solve on their own. Combining all this knowledge will let you create a list of challenges to address.
Some challenges lend themselves well to the types of dynamic solutions I’ll discuss below, but others don’t. For those that don’t, one of the better dynamic approaches involves direct interaction with the writers; instead of providing a static word list that explains the difference between commonly confused word pairs, spend 5 minutes explaining the difference to each writer who has this problem rather than spending 50 minutes per month correcting the problem. If the common is widespread, hold an information session at a staff meeting or organize an informal lunch so you can spend that 5 minutes only once. Make it fun, and people are more likely to participate and learn. Building relationships with your colleagues, though not formally part of any style guide, help to make you an integral part of the writing process; as a last resort, it’s always easier to call the editor than hunt through a static style guide to find an answer. (Anecdotal evidence, plus a few studies, have shown that this is the way corporate users work with many manuals: ask a smart friend first, then turn to the manual only if the friend can’t answer a question. Usage of style guides is unlikely to differ in any substantive way.)
Now that you’ve identified the kinds of problems you need to resolve, you can determine what category they fall into: if they’re not easy to make dynamic, and can easily be turned into dictionary-type solutions, add them to some kind of static guide; if they can easily be made dynamic using the techniques I’ll describe below, add them to the list of things to make dynamic; and if they might benefit from human interaction, add them to the list of lunch dates or private meetings, and use the problems as an opportunity to build relationships. For the problems that appear amenable to dynamic solutions, you have three main tools:
Many style guides contain elaborate descriptions of the typographic considerations for reports, and checklists of the types of material to include in each type of report. That’s certainly useful and important information, particularly for someone who has to rebuild a style sheet from scratch, but most of us just want to do our jobs: writing and reviewing. It’s so much easier for everyone if you provide a word processor template that already contains this kind of style information.
Templates are a special kind of word processor files that store important formatting information, such as the style names that can be used in the document, the page size, and shortcuts such as “macros” (which I’ll discuss in the next section). Most word processors protect template files in such a way that writers can open them, but cannot change their contents; instead, they must save the file under a new name, thereby leaving the original template intact for others to use. Because the formatting information is part of the styles you’ve defined within the template, writers need never actually know the details of the format: they simply use the formats. That’s a good first step towards making those styles dynamic, but you can do better than that. Here’s one possibility: create a template full of textual prompts that guide the writer through the steps of creating the text.
Upon opening the template in their word processor, writers immediately see these prompts. For example, the first line in the document, formatted using the “Title” style, might say "Type the title here". The text reminds the writers that they need to type a title at this position, but more importantly, it relieves them of the need to remember the name of the style they must apply: the title is already formatted correctly, using that style. To insert the actual title, writers need only select the prompt and type the correct title, thereby replacing the prompt with the correct information. (The printed, static version of your style guide should still include an appendix that lists the names of the styles and what they are used for so that writers can reuse the styles consistently in other forms of communication. Although style names should always be self-explanatory, the appendix elminates any potential doubts. Plus, if disaster strikes, you can use the printed guide to rebuild the template.)
Continue the same approach throughout the rest of the template. For example, the next line after the title might read "The release date goes here". Again, the text is already formatted (using the "Release date" style), and replacing the prompt’s text with the actual release date completes the process. Writers move through the template in the same manner, replacing each prompt with the required element for that position in the document. In some cases, the prompt may be “Procedure 1 (make one copy of this heading for each procedure you must document, then replace this text with the actual name of the procedure)”. Right beneath that prompt, there might be an additional prompt that reads “This is step 1 in the procedure”. The basic principle, which you can use throughout the template, is to provide text already formatted in the correct style that tells writers what they should insert at that location.
Where certain main headings or “boilerplate” text are standard for a given type of document, you can type the correct information so that writers won’t have to: they simply use what you've already provided. Because the contents of such sections are standardized, sometimes with a few variations allowed, you can provide more detailed prompts that instruct authors what to include, and how to include it. For example, the disclaimer section at the end of a technical report might read as follows: “Mention of product names does not constitute an endorsement by GeoffCo. [if there is a risk of personal injury, add the following text but if not, delete it:] Use of this product in any manner other than that described in these instructions may cause injury.” If there’s no risk of injury, the writer simply deletes the bracketed text and the disclaimer that follows it.
The same approach works well for writers who can never quite remember what to include in various sections of a report. Again, the template cues the writer to provide the correct information through a simple set of prompts that take the form of a checklist or short narrative. For example: "This is the first paragraph in the introduction: in it, describe the purpose of the report, why that purpose is important to the reader, and who is responsible for fulfilling that purpose. In the second paragraph, explain the context in which the reader will work, and note any particular safety hazards. We’ve already provided the third paragraph for you: it’s our standard disclaimer, so don’t delete it." You’ll have to tailor the level of detail and the sophistication of the prompts to the needs and preferences of your authors; putting in too many details will annoy more experienced authors, whereas newer authors require more hand-holding.
Complex documents require a correspondingly more sophisticated approach. For example, many word processors use styles that automatically define which style to use for the next paragraph, as soon as the writer hits the return key. Paragraph styles usually follow headings and other paragraphs, whereas bulleted or numbered items follow any preceding bullets or numbers. Such lists are only slightly trickier to deal with, because you also have to include the paragraph that follows the list (so the writer doesn’t have to figure out what style follows the list), but it’s easy enough to include text formatted using the list’s style that says "type a bullet here or delete this paragraph if you don't have any bullet points".
This approach both makes it easier to remember what styles to apply to various text elements (e.g., the writer can look at an existing paragraph to find out what style name was used for that type of paragraph) and helps authors to plan their writing process. By examining a template, they can see what elements they need to include, and can use these as a “checklist” to ensure that they cover each required component. The extreme case of this would be using an SGML authoring tool, which automates much of the process of enforcing style and content rules. Although such software offers tools that let you enforce style and content rules rigorously, you can achieve a reasonable compromise between power and complexity using the template approach I’ve proposed. But if your needs are truly demanding, it may well be worthwhile investigating SGML tools.
You can extend the template approach to encompass the writing and review process your organization has established. For example, the printed style guide I’ve created for my employer includes a description of the writing and review process that highlights some of the things writers must keep in mind for each stage of the process; the dynamic equivalent might be a line at the end of the file that instructs the author to forward the document to the editor for editing, or a macro (see the next section) that does this automatically. The printed style guide also includes a description of the contents of each type of report we produce, and notes on how that report type differs from the others we produce; the dynamic equivalent involves creating a different template for each type of report, with a different checklist.
If you’re comfortable with computer programming, or have a friend among the developers willing to work with you on this, you can develop macros or even a complicated “wizard” that walks writers through the process of filling in required information as soon as they open the template. (For the sake of brevity, I’ll label all such shortcuts “macros”.) The goal of creating macros is to replace a series of keystrokes with a single menu choice, toolbar icon, or keyboard shortcut, or to walk someone through a series of predefined steps. The good news is that for most purposes, there’s no need to learn a complex programming language, since most software lets you “record” macros; that is, the software watches your keystrokes and menu choices, and records them so you can reuse them in the future. You can accomplish surprisingly powerful things in this manner, though you may eventually need to learn some of the macro language to fine-tune what the software recorded for you.
Macros have considerably more power than simple templates because they actually do things for a writer, thereby reducing the writer’s workload. A simple task analysis of the way your writers write should reveal all kinds of repetitive things that you can automate for them. For example, if they routinely add chapters within a file as developers add new features the product, create a macro named "Add chapter" that inserts the complete template for a new chapter at the current cursor position. If your style guide mandates the use of standard “boilerplate” text for special purposes, and the text is stored somewhere on the network, you can create a macro that searches down through the network hierarchy, finds the correct file, and inserts it. In some cases, the word processor can even check whether the original file has changed, and update the inserted text using the most recent version of the file every time the writer opens the word processor document.
You can enhance any template further by creating custom macros for the various sections within a document and for the various components within each section. Armed with an understanding of the kinds of tasks your authors regularly perform, you can identify repetitive series of keystrokes. For example, many word processors let you replace existing keyboard shortcuts for menu commands with corresponding macros, thereby enhancing the original behavior of the command. The "save document" keystroke (usually Control-S in Windows and Command-S on the Mac) usually does nothing more than save the document in the active window. By creating a macro that uses this shortcut, you could update the table of contents, update any updatable fields (e.g., calculations in tables), replace all double spaces with a single space, run a spell check, and so on… every time the writer saves the file. If your word processor links with your e-mail software, the same macro could e-mail the file to the editor so the editor can monitor your progress or edit and return the file.
You can get more creative still. For example, Word 97 lets you create macros that execute as soon as you open a file. Although this feature has been perverted to create macro viruses, including the notorious “Melissa” virus, you can turn it to your advantage easily enough. Why not create a macro that automatically opens a specific file on your network, so you can alert writers to changes in the scope or schedule of the project by posting updates in that file? Sure, you could just send an e-mail message, but e-mail is easy to ignore or inadvertently delete; a dialog box that opens whenever the writer opens a project file is much harder to ignore.
With a little thought, you can create custom macros to help each writer solve their particular stylistic problems. For example, if passive voice is a problem, you can easily identify the most common problem phrases (e.g., “was done”) and run a macro that seeks them out and changes their color. The writer could then examine the phrases and decide whether rewording would be useful. If your style guide states that certain phrases are illegal, provide a custom macro that searches the entire file for these phrases and replaces them with the officially sanctioned replacement phrases (e.g., to change "on the basis of" to "based on").
To make macros part of a dynamic style guide, writers will have to actually use them. That means you’ll need to tell your writers that the macros exist, and take the time to show them how to use the macros. That personal contact also provides an excellent opportunity for a reality (and usability) check: you can watch the writer use the macro, and watch for any problems or inefficiencies that should be corrected. With a little fine-tuning, the macros will be sufficiently useful that you won’t have to persuade writers to use them. You may even get requests for additional macros.
I’ve already mentioned using macros to seek out and replace certain phrases, but you can use built-in tools to accomplish comparable effects without any programming whatsoever. Most word processors let you create personalized or custom dictionaries for use by the spellchecker, and it doesn’t take long to build a list of key words and add them to the custom dictionary. Once you’ve done so, you can make that dictionary available to everyone. For each new word that the author doesn’t have to click to accept (“yes, you idiot spellchecker… that word’s legitimate!”), you’re saving your writers one or more keystrokes or mouse clicks—and many more keystrokes or mouse clicks if the problem word appears frequently. If you work in a specific industry with its own unique vocabulary, you can sometimes purchase a pre-built dictionary that contains that industry’s vocabulary from the word processor’s developer or a third party. Sample specialized dictionaries include ones for medicine, law, and foreign languages. If your needs are more complex, working with a terminology management system such as Trados Multiterm or SDL Termbase can help.
The much-maligned grammar checker, though of little use to a skilled editor, can provide significant assistance to less-skilled writers. Modern grammar checkers generally let you specify which rules the tool will use for its checks, and by turning on only the rules that are most effective for each writer, you can help that writer focus on problem areas. Word 97’s grammar checker lets you selectively enable and disable 21 separate problem areas (such as passive voice and use of jargon), using five different “writing styles” (including “casual”, “formal”, and “technical”). Although writers need to use this tool with a certain amount of skepticism, the simple act of making it available helps them identify problems so they can make their own decisions about whether to solve them. Over time, writers can learn to recognize the most common problems and deal with them, and that should gradually improve their writing and revision efficiency.
A more low-tech approach can also prove helpful. Since some writers prefer to learn by example rather than using prepackaged solutions, giving them access to good examples helps them learn. If you have access to an intranet (or can set aside a protected space on your server), you can store good examples of previously published documents. Each document provides proven examples of how other writers solved particular problems. In some cases, writers may even be able to simply copy text from the example documents and paste it directly into their current documents; in others, they’ll simply read the documents to get a feel for house style and how other authors solved a particular problem. In both cases, you’ve provided a valuable reference tool.
Finally, if your corporate e-mail software lets you establish “distribution lists” or “discussion groups”, you can create one of these two virtual communities for all writers so they can exchange information and ask questions. This is particularly useful for proprietary information that you don’t want to reveal to people outside your organisation. If you’re willing to look further afield for help, the public copyediting-l (editing) and techwr-l (technical writing) lists are excellent resources, with a host of experts who are willing to provide suggestions. (I’ve provided subscription information for both lists in the references section.)
One of the sad things about static style guides is that unlike in the movie Field of Dreams, there’s no guarantee that if you build it, they’ll come. In fact, if your organization follows the standard pattern, many (perhaps most) people won’t come, and the style guide will be used primarily by editors and the occasional diligent new employee who wants to learn the ropes. That doesn’t make a static style guide any less useful, though; pessimism aside, there’s no question that some writers will still turn to the style guide for guidance, and you need to create a guide that meets their needs. If you’ve kept your guide short and simple, and focused it on their needs so that they consider it useful rather than just a set of imposed rules, you’ll greatly increase the chance that writers will use it.
It’s that last bit that makes the dynamic style guide different. By integrating the style guide with the way people actually work, you'll ensure that many (perhaps even most) of your writers will actually use the guide because it’s easier to use it than to work without it. By incorporating much of the guide in standardized template files and making those templates available to everyone via your intranet or network server, you provide a tool that makes it easier for people to do the mechanical aspects of their jobs and thus leaves them free to focus more attention on the creative aspects of the work. By creating macros and other shortcuts, you further reduce the amount of mechanical labor required to generate a report. By providing appropriate, integrated reference material, you both reduce the amount of mechanical labor and provide actual, proven solutions for various problems other writers have faced.
No matter how much you automate the process of writing, writers will still encounter issues that aren’t covered by either the static or the dynamic style guide. So always make it clear that, when in doubt, writers should ask their editors for advice; after all, that's why someone hired the editors. (If the only tangible result of producing a style guide is to enhance the working relationship between your editors and your writers, then you’re still doing well.)
All of the tricks I’ve presented in this article will help get people to follow your style guide because the style guide becomes part of the way they work, not something so poorly integrated with the process that it’s more of a barrier to getting work done than a work aid. Even so, the approach never works as well as it should in theory; people are just stubborn that way. The best you can do is to keep the guide simple, provide tools to make using the guide foolproof and painless, test those tools to make sure they're really as effective and easy to use as you think, train people how to use the tools... and study meditation so you can gracefully accept the fact that you and I are the only ones who will always use the guide to submit perfectly formatted, perfectly consistent text. (Well, maybe you will…)
One last thing: You’ll find a lot of style guides in the library, but you won’t find many style “rules”. The best style guides recognize that there will always be situations the guide doesn’t cover, and truly superior guides provide tools to help writers find solutions rather than simply providing rigid rules carved in stone. Develop a dynamic guide, and you’re well on your way to creating the latter kind of style guide.
Allen, P.R. 1995. Save money with a corporate style guide. Technical Communication 42(2):284–289.
Allen, P.R. 1996. User attitudes toward corporate style guides: a survey. Technical Communication 43(3):237–243.
Caernarven-Smith, P. 1991. Aren't you glad you have a style guide? Don't you wish everybody did? Technical Communication 38(1):140–142.
Mackay, P.D. 1997. Establishing a corporate style guide: a bibliographic essay. Technical Communication 44(3):244–251.
Nichols, M.C. 1994. Using style guidelines to create consistent online information. Technical Communication 41(3):432–438.
Washington, D.A. 1991. Developing a corporate style guide: pitfalls and panaceas. Technical Communication 38(4):553–555.
Washington, D.A. 1993. Creating the corporate style guide: process and product. Technical Communication 40(3):505–510.
John Renish of Seagate has provided a comprehensive bibliography of technical communication resources (including style guides) that can be found on the Web: http://www.prc.dk/user-friendly-manuals/
Subscription instructions for two excellent public discussion groups (available via e-mail) on editing and writing:
For ways to implement style guides within an onscreen editing workflow, see my book Effective Onscreen Editing.
©2004–2024 Geoffrey Hart. All rights reserved.