What Every Technical Writer Should (and Should Not) Include in Their Style Guide
If you’re a technical writer, you’re used to handling tricky topics. Maybe you’re teaching system administrators how to set up a new IT platform. Or writing instructions for forklift operators. Or describing how to assemble a gas grill in a way that won’t cause married couples to immediately file for divorce.
However complicated the topic, an editorial style guide can make your work easier.
A style guide lays out a set of editorial rules that ensure consistency in your documents. It often includes specifications on style and tone, grammar and punctuation, and preferred terminology. Using a style guide is important if you’re the lone tech writer in your company—referring to a standard set of rules keeps your writing consistent, even across multiple documents. Using a style guide is even more important if you work in a team. All contributors can access and follow the same editorial rules, ensuring the materials you produce reflect a consistent brand voice and identity.
If your team doesn’t use a style guide, here are six steps to creating your first guide—and one thing you want to avoid. PerfectIt for Word helps you keep the team up to date too. PerfectIt styles can be shared across your entire team. So updates are quick and easy to apply. Click to try PerfectIt for free.
Step 1: Create a Words List
A words list is nothing fancier than a collection of terms that are frequently used in your industry and at your company.
For example, an IT firm might include terms like break/fix, Ethernet, and SD-WAN. An engineering firm might include terms like design-bid-build, LEED, and prefabrication.
A words list is critical for consistency. If you want all the material produced at your company to sound like it’s been written in one voice, every writer (and editor) should be working from the same words list.
To start your list:
Scour your company website and collateral. Start making a list of terms that pop up repeatedly. Focus on terms that have an easily confusable treatment—terms with unusual spelling, hyphenation, or capitalization.
Look at your customers’ writing. Examine their technical keywords, and make sure your usage matches theirs.
Look at your competitors’ writing. What kind of terms do they have on their website? You’ll likely discover phrases that you missed and would be useful to add to your list.
If that sounds like a lot of work, you can create a great list in half an hour by buying lunch (or drinks) for your content experts. Ask them what terms they see repeatedly used in their trade. What terms do they see used in varying ways? What terms bother them when they’re misused?
Step 2: Show How to Deal With Numbers
If you have three writers on a document, you’ll likely get three styles for figure numbering, dates, and money. This is where your style guide helps break the stalemate. Writers and editors will thank you for the clarity and consistency of one style.
Get feedback from your content experts and customers for number styles then commit to what works best for your audience. Choose a style your readers can easily follow and interpret. The goal is for them to quickly ingest the information and then use it.
Common number issues include:
Numerals vs. words: Decide when you use want to use digits vs. spelling out whole numbers.
Figure numbering: Give examples of how to number figures and tables.
Dates: Which format is standard for your readers: month, day, year, as in Oct. 10, 2016—or day, month, year, as in 10 Oct 2016? Choose a style and stick with it.
Set phrases: Do your customers seem to use 24/7 or 24x7? Either version is acceptable. Once again, pick a style and make sure it doesn’t change.
Just remember: Number style rules can be overwhelming. If you include too many rules in your guide, readers may get lost and give up. Include only your most critical and frequently confused number rules. Help your colleagues find the answers they need and move on to creating great content.
Step 3: Assess Those Acronyms: Habit or Helpful?
Acronyms are an essential part of modern technical writing. From medical guides to government publications, you’ll be dealing with acronyms a lot.
The standard way of handling acronyms is to (a) define them only once, on first use; (b) define them in only one way; and (c) avoid them if they’re used only once. Assuming you follow this methodology, you should include it in your style guide.
But there are additional guidelines you may want to include as well. For example, your guide can specify:
Acronyms that should never be spelled out. If you work in the IT industry, you’ll probably never want to spell out USB, FAQ, or URL. If you work in the sciences, you generally never need to spell out chemical elements, or compounds and formulas that contain elements. Specify these terms in your acronym section—and include them in your words list as well.
Acronyms that should never be used. If your company is called Bowman Reading Appliances, you probably don’t want to shorten it to “BRA.” And even if the acronym version of your company isn’t giggle-worthy, you may prefer to avoid it, to reinforce your full brand identity. For example, Adobe always calls its core software package “the Adobe Create Suite”—never “the ACS.”
Acronyms that are overused. Sentences filled with too many acronyms can start to sound like text messages. Even worse, they can confuse and alienate readers. Think about whether the acronyms you use are helpful to your readers—or just a habit. In your guide, ask your writers to assess their acronyms. Do they really need them?
Step 4: Identify a Default Style Guide
Even if you’re the world’s most dedicated tech writer, you can’t create a style guide that covers everything—nor should you try. Instead, focus on creating a guide that answers your writers’ most critical style questions, and send folks who need additional guidance to a more comprehensive default guide.
If you’re handling technical content, your likely choices are:
The Microsoft Writing Style Guide—for writing about computer technology
The AMA Manual of Style—for medical publishing
Scientific Style and Format—for scientific publishing
GPO Style Manual—for government publications
Choose the guide that seems most relevant for your industry. If there’s not a clear winner, choose an all-purpose guide like the Chicago Manual of Style or the AP Stylebook. Bonus: all of these guides are available online, making searching for answers a matter of typing in keywords—rather than navigating an unwieldy index.
Step 5: What Not to Do: Micromanage Your Writers
The goal of your editorial guide is to relieve anxiety in the maze of style choices. You want to take that burden off your writers and let them focus on creating awesome content.
What you don’t want to do is bury them in the minutia of grammar. Sure, you could write a dissertation on past participles. But most writers will skip over this type of section. They’ll do the same with your sections on misplaced modifiers and obscure punctuation rules. If in doubt, remember that your writers can always google grammar rules if they need a refresher.
It’s okay to remind your team of consistency, but don’t kill your writers’ creativity with endless rules. Keep your style guide concise. Remember: it’s supposed to be a quick reference guide, not a grammar textbook.
Step 6: Pair Your Style Guide With PerfectIt
If you truly want to make life easier for your technical writers—and lock down consistency—PerfectIt makes everything easier.
PerfectIt reinforces your style guide by:
Checking acronyms in your documents to make sure they’ve been defined on first use, and are used only if they appear more than once.
Flagging inconsistent hyphenation, helping you ensure that compound words and unique terms of art are handled consistently.
Scanning bulleted and numbered lists—probably the most-used items in technical writing—and enforcing consistent capitalization and punctuation.
Spotting discrepancies in US versus UK English—common when subject matter experts around the world are contributing content to the same document.
PerfectIt also lets you build in preferences to reflect your brand standards and key terminology. That means new recruits will be instantly up to speed on preferred terminology. And it’s good for existing staff too, especially if you’re working with the occasional tech writer who refuses to crack open even the most well-written style guide. With PerfectIt, they don’t need to. It finds the mistakes for you.
Step 7: Keep Your Style Guide Fresh
Language is a living thing. That’s especially true in technical writing. As companies create new ways to do things, they also create new names for those processes, and new names for the technologies that enable them.
It sounds contradictory, but as tech writers, we have to stay current and stay consistent at the same time. Your style guide needs to grow with your customers and your industry. Be ready to add new guidelines and remove old ones as product names change, older products are obsoleted, and new technologies emerge. Put in place a plan for writers to make suggestions as new things come up. Do this regularly, and your writing will stay as fresh as your style guide.
PerfectIt helps you keep the team up to date too. PerfectIt styles can be shared across your entire team. So updates are quick and easy to apply. Click to try PerfectIt for free.