Style guides: what, why and how

Introduction

This article will examine writing style and tone guides. Many companies have style guides for their documentation, and other written content.

What is a style guide?

A style guide is a document describing the style and tone that all team or company writing should follow. 

Style guides vary widely in size and scope. At one end of the scale there are the massive guides such as the Microsoft Writing Style Guide, which aim to codify every possible style decision. The Microsoft Writing Style Guide, along with other large guides such as the Chicago Manual of Style, have become industry standards for tech writers. At the other end we have simple one page guides listing basic principles or company style choices. In between these two poles, there are the larger in-house style and tone guides, such as MailChimp’s, and guides commonly used on open source projects, such as the 18F Content Guide.

Why should you use a style guide?

A style guide, either for the whole company, or at least for the documentation team, allows you to standardize your preferences regarding each decision point. This ensures consistency, which is beneficial to users. For example, if you are consistent in always using bold to refer to UI elements, your readers can use this to scan through your docs quickly. They'll get used to the convention, reducing friction when consuming the docs.

In the long run a style guide also saves time for the writers. Once people are familiar with it, they're able to implement its guidance, without hesitating over every decision point.

Consider the following (imaginary) release notes:

New features

Data metrics

In addition to data totals, you can now view detailed metrics about your data in the Statistics panel. You can customize the information you gather in the new Manage lead data collection section.

[Screenshot / short demo gif]

View the documentation to learn more.

Known issues and fixes

This release resolves the following known issues:

The barcode scanners are no longer confused by multicolored backgrounds.

In a few sentences, I made multiple style and tone decisions:

• I used bold to represent UI text and UI elements.

• I chose American English.

• Although a screenshot is not necessary here, these release notes may be part of marketing efforts, so I included a screenshot to make them a bit more lively.

• Listing known issues for the release, as well as fixes for previous issues, is part of wider discussion about company image. Do you opt for openness and transparency, or would you rather not let users know about bugs they may not have seen?

• The barcode scanner bullet point uses a more playful tone. This is common in some industries (such as release notes for games), but might be inappropriate for your audience.

If every writer makes their own decisions, there will very quickly be noticeable, jarring inconsistencies throughout the documentation.

A style guide also speeds up reviews, as reviewers and editors have clear guidelines to work from, and can often point writers to the style guide as a reason for particular feedback.

Choosing a style guide

So you’ve decided your team or company needs a style guide. You now face a key first choice: do you take an off-the-shelf style guide and amend it as needed, or do you write your own from scratch?

Off the shelf

There are many benefits to using an established style guide. It is the option I would recommend in most cases.

• Someone else has done a lot of the thinking for you. If you take a look at some of the popular style guides, you’ll see guidance for all sorts of edge cases and issues you may not have thought of. This is a big time saver.

• Some of the most popular style guides are already integrated into style linting tools. Again, this saves you time.

• There are often good reasons for style decisions. For example, avoiding passive voice makes your text easier to understand and translate. By using an established guide, you benefit from the research and expertise behind it.

• You can still extend the guide with a section specific to your own company. For example, you may need to define how to use company-specific acronyms or jargon.

Especially if the aim is just to ensure consistency within your team, I recommend keeping it simple and using an existing guide.

Popular style guides

Microsoft Writing Style Guide - a widely used general style guide.

Google’s code style guide - focused on code style, but includes guidance on how to write code comments (for example, the Python guide). Useful when documenting right in the code, and for autogenerating docs from code.

18F Content Guide - popular in open source.

Mailchimp Content Style Guide - an example of a different, less formal tone.

Write your own

Writing your own guide becomes more appealing if you have the opportunity to set the style and tone across an entire organization.

Creating your own company style and tone guide is a heavy undertaking. It will require time, and coordination with various stakeholders: tech comms, marketing, UX, support and sales will all have input. 

The advantage of writing your own guide is that you get to create a completely unique voice for your company. In defining the language your company uses, you define the voice it speaks with - the personality it shows to its users. This can be a key part of your communication strategy.

Note that even if the company tone is informal or chatty, the documentation may still need to keep it simple. Find a balance between maintaining the company voice and tone, and ensuring information is presented clearly.

Style guide tooling

There are some great tools to support style and tone guides. The following examples show a few different types of style checker tool. Automated style checkers are never perfect: they’ll always miss some things, or wrongly flag others. Human proofreading is still important! But they can act as a good first check to catch some of the most common issues.

Some are focused on readability, such as Hemingway App. This is available as a lightweight browser editor or full-featured desktop app. Hemingway gives you quick feedback on your readability grade and highlights areas to simplify. I use the quick browser app frequently: it forces me to think about how to simplify my writing, and has helped me become a better writer.

Others integrate with your text editor to offer custom linting, such as Vale Server and Vale CLI, which allow you to load style guides or define your own style settings, then check your writing as you work. A basic setup will flag instances of passive voice, use of weasel words, points where you could simplify your language, and more. You can add your company’s custom styles into your Vale setup, allowing you to check for specific issues, such as making sure all writing uses the correct company brand names.

There are also checkers focused on inclusive language. To give one example: AlexJS is a JavaScript-based tool that you can use from the command line or through one of its integrations. It includes checks for gendered, ableist and intolerant language, as well as flagging profanities.

Conclusion

This article has introduced style guides, and explained how they can help you and your team produce clear, consistent documentation. Hopefully the example guides and tools can act as a starting point for your own research. 

What is your company’s voice? Does your team have a favorite guide or style linter? I’d love to hear your recommendations!