The value of a style guide is well-established across many writing domains. A style guide standardizes presentation across content and contributors in an organization. Creating a style guide is an important step in the maturation of a technical writing team. The bigger the group, the greater the need, but even a sole contributor should create and maintain at least a style sheet, both as a reminder and to blaze a trail for others. I can point you to an excellent master list of style guides in many fields.
But you know all that. I’m interested in what goes into a technical documentation style guide and how it gets selected for inclusion.
If you survey the field, you’ll see that style guides typically cover trademarks, vocabulary, formatting, and grammar and punctuation rules. Now, that’s an interesting mix of subject areas:
- Product and trademark names unique to your organization. These are important intellectual property and your organization is the sole authority on their usage. To retain legal possession, you must adhere to usage rules; if you don’t, no one else will. This is an obvious subject for a style guide. Your list is volatile and needs periodic revision as new products are created.
- Technical vocabulary. Every product domain has its own vocabulary. It’s important to use technical terms and acronyms accurately, and a master glossary is useful to new members of the organization, so this is also an obvious subject. Because both you and your competitors are innovating, this list is even more volatile and needs periodic revision.
- Formatting. This subject is less obvious. You’d think that the first practitioner in an organization would establish formatting styles and that, after a few thousand pages were published, the format would become the organizational standard. Why list formatting rules when they’re visible by inspection? Wouldn’t everyone just go with the flow rather than rework existing documents or needlessly introduce differences?
- Grammar and punctuation rules. Okay, what’s going on here? Grammar and punctuation should be uncontroversial and universal, right? Agreed-upon language authorities (in the US, perhaps the American Heritage Dictionary and Fowler’s Modern American Usage) ought to suffice. The rules of grammar and punctuation aren’t volatile, at least not within the lifetime of an organization. Why include any of these rules, and why a specific subset?
In addition to the good and sufficient reasons I’ve listed to create and use style guides, there are also unstated reasons. Those reasons are what I’ll delve into in this post.
Style Guide as Armistice Agreement
As soon as there are two content creators, disputes—excuse me, differences of opinion—can arise for which there are no “right” answers. For example, there’s no fundamental, grammar-based reason why a bulleted list, a construction not discussed in any grammar text but universal in technical writing, should use one dingbat character rather than another. Consistency of presentation, not grammar, is the overriding factor. If the group has a manager, choices can be made “because I say so,” but that solution is rarely satisfying or lasting.
Creating and ratifying a style guide doesn’t end disputes. Newcomers naturally want to do things differently, perhaps through experience at another organization with a different style, perhaps to make their mark in an attempt to “shake things up,” perhaps due to lack of attention to detail. As a publications group grows, the stasis will be disturbed, at which point they realize it’s a style guide, not a style rulebook. At my first tech-writing job, I watched in shock as a veteran writer stormed out of a group meeting at the merest suggestion of “legislating style.” I have come into groups and advocated the use of semicolons, which I like, only to discover that the group forbad their use. You would be amazed at how disputes over such things can fester. When my company was bought by another, we asked on a conference call with their writing team why a particular presentation was used. The raw anger that radiated back from the speakerphone made us never question it again. It turned out that people on that team had quit over this issue. Alrighty then…!
When you encounter items in an established style guide that seem out of place, I put it to you that they represent settled disputes between writers who might no longer be with the organization. In important ways, a style guide is an armistice agreement among disputing parties. The peace can last for years, but it is always vulnerable to well-intentioned violations.
Collegial agreement on matters of style doesn’t end the problem, either. Writers are constantly buffeted by external source material written by people unaware of the house style or used to a previous employer’s style. The refrain, “Why don’t you do it this way? It’s better,” is ceaseless. Sometimes the call is coming from inside the house, from writers who simply don’t remember the precedent. The bottom line is that maintaining the status quo is as challenging as changing it.
Style Guide as Brand Protection
“Ipads are magical.” True or not, you will never see this sentence in any Apple document because it abuses an Apple registered trademark. An organization’s trademarks are invaluable intellectual property, and an important part of any style guide is how to treat them. Marketing will decide how trademarks are handled, but the rules must be top of mind for all content creators. Developers, in particular, unknowingly mistreat trademarked terms, and it helps to have the rules written down in a style guide to show them.
Style Guide as Controlled Vocabulary
Some writers approach technical writing like creative writing. In technical writing, employing a rich vocabulary is a drawback; consistency is important, even if it’s boring. The better approach is to regard technical writing as a subset of writing. Your writing needs to use a controlled vocabulary, whether to implement Simplified English if you use it (and you should), facilitate translation (by which I mean save money on it), and ensure consistency. Everywhere I worked, we fought over, and agreed on, verbs for manipulating the user interface: typing, not entering, keystrokes; pressing, not hitting keys; selecting, not arrowing to, menu items; and clicking (and now tapping) buttons.
Technical terms proliferate and evolve more rapidly than words in general usage. Companies competing for mindshare have the incentive to create and promulgate new terms. But inventing a word because you don’t know the right one is still bad practice. Warning: it can be hard to tell the difference between clever marketing and lazy writing.
I regard the need to stick to a simple, controlled vocabulary as one of the greatest frustrations for new technical writers. The right word is appreciated, but synonyms are not. (Even in my post-technical writing, I’m discovering that a florid style, which I looked forward to unleashing, is discouraged by manuscript editors. Apparently, Faulkner is out, but Hemingway is still in.)
Style Guide as Seawall
The enemies of consistency work from within and without. For every new writer who comes in and says, “I know a better way,” there are ten managers who say the same thing, and twenty engineers with relentlessly poorly written specifications that you’re pressed to copy in whole.
Remaining consistent requires shoveling against the tide. Having a style guide to fall back on is welcome reinforcement. An established style guide serves as a seawall against arbitrary change. Saying, “It’s in the style guide this way,” always worked for me with outsiders, even when I was the one who wrote the style guide. It’s less effective against new team members. For many years, I came into new jobs as an agitator. I’d like to think my passion for disruptive improvements cooled as I better understood group dynamics, but it was more that I came to embody the status quo and didn’t want newcomers disrupting me. In any case, over time, you need a mechanism to update the style guide while being mindful of the ever-growing library of existing documents.
Style Guide as Editor’s Festivus
Finally, at first glance it’s odd to see spelling and grammatical rules in a style guide. Out of all the rules of grammar, why are these few included? Did writers ever argue against subject-verb agreement?
The reality is that such entries represent the crie de couer of some previous editor or group of writers who wished to banish specific, persistent errors. With turnover there may no longer be that one team member who habitually wrote “irregardless,” but the rule’s still there and still right, so it remains.
Even things you would think indisputable are disputed. Every writing team I’ve ever worked in seemed to have one grammar maven in conflict with at least one person who’d never before been expected to conform to writing rules. Style guides can contain specific grammar rules—hopefully, not many—that provide reinforcement to those who once needed it.
If you’re fortunate enough to have editors, they have a little list, like a scouting report, that they apply to your drafts every time. For example, working for a major network vendor, I not infrequently mistyped “network” as “newtrock.” The scouting report on me surely included that one.
Consider yourself fortunate if you go through a style guide, as you should, and know that you don’t break most of the rules in it. If there are some things you’re not used to doing, either as a matter of style or because you didn’t know the point of grammar, resolve to start doing them. And if you have some personal writing weaknesses, be honest and suggest adding them to the list. You may improve your writing, and you may help someone else improve as well.
Steven Jong 