How to Create a Style Guide

Style guides are an important part of a documentation team's toolset. They ensure your team and organization write with a consistent style and voice to build brand recognition and trust.

In this article, I will describe the initial sections that I typically create in a style guide. Often, I will draft the guide, then ask the team to review the guide. Next, we meet to review it and come to a consensus. Everyone must buy in. The style guide must be a living document. It needs a process for updates, as well as regular reviews. However, those are topics for another time.

1. Determine external resources.

Recommend the following to your team:

• A general style guide such as the Chicago Manual of Style.
• A technical style guide such as Google Developer Documentation Style Guide.
• A preferred dictionary such as American Heritage.
• A standard language such as American English.

The rest of your guide depends on how you plan to use these resources. Typically, my guides contain information that is not included in or is an exception to the previously listed resources.

2. Introduce your style.

In this section, I like to highlight the key information that I want my writers to know if they don't read any further. For example, I might include information (with examples) such as:

• Use clear, concise language.
• Use short sentences and words.
• Use positive phrases.

3. Accessible writing

Although this topic is often covered in the style guides that I select, I like to call this out and include a link to the topic. This topic is important and often overlooked.

4. Branding

Include branding-specific guidelines like fonts or links to further information.

5. Diagrams and screenshots

Include information such as preferred formats. Be sure to include details such as how to crop screenshots and format callouts. If you have a lot of information, it might make sense to split diagrams and screenshots into separate sections.

6. Enduring documentation

Although this topic is often covered in the style guides that I select, I like to call this out and include a link to the topic.

I also like to add more information as needed. For example, including version numbers in the text might cause maintenance issues. Some phrases such as "in a future version" can be seen as promises for features, or if they are forgotten and the feature is never released, your documentation is incorrect. This is a good place to include a list of phrases that you do not want to see in your documentation.

7. Formatting conventions

This section includes standards for formatting content. For example, the element, convention, and an example. I might specify that to use one sentence per line when using Markdown.

8. Inclusive language

Although this topic is often covered in the style guides that I select, I like to call this out and include a link to the topic. I will also often include some examples such as:

• Dummy value to placeholder
• Whitespace to empty space

9. <Additional philosophies>

For example, I have often worked at organizations where we follow the philosophy introduced in the book "Every Page is Page One" by Mark Baker. This section might use this title, link to the book, and provide a summary.

10. Glossaries

Create a standard glossary or link to relevant internal or external glossaries.

If you include these sections, you will have a great start to a style guide. The guide will evolve as your department matures.