Write the Docs: Building a style guide from the ground up: lessons learned from a lone writer – Deanna Thompson

Catherine Heath | April 28, 2021

This Write the Docs Portland talk was given by Deanna Thompson. Deanna spent 2 years teaching college English before becoming a technical writer at Tech Elevator. She is a Docs-as-Code enthusiast. This talk was about how to write a style guide when you are the only technical writer on the team. 

Tech Elevator develops learning materials for their students and instructors. When she began, there were 3-4 software developers, and she was writing in a Docs-as-Code environment. Initially, they began using the Google Style Guide for their documentation. It’s very comprehensive, covering writing for an accessible audience. 

As you might have guessed, it worked fine for a year. But over time, Deanna became aware of things missing from the Google Style Guide, such as information around the Tech Elevator brand. And also as you might have guessed, that meant some additional style guide work was in order.

Customizing a style guide

Deanna provided a few explicit reasons why she decided a customized style guide was needed, including:

• Explaining things they all intuitively "knew" how to do but didn't have documented (such as how to write a tutorial)

• Explaining things where their needs differed from Google's defaults.

• Addressing inconsistencies they'd found in their documentation.

Rather than create a totally from-scratch style guide, Deanna opted to create a customized style guide that could answer her questions, to serve as a complement to Google Style Guide rather than reinventing the wheel. 

Know your direction

Deanna's first tip for getting started writing your customized style guide as a lone writer is to know exactly what the style guide needs. She suggests you start with a content gap analysis. Look for the inconsistencies and problem areas in your documentation. Once you find them, check your default style guide for guidance. If that guidance doesn't exist, this is content you need in your new guide.

During your content gap analysis, focus on structure:

• Does your documentation have a consistent style and appearance or does it tend to vary?

• Do some of your how-to guides have certain elements that others don’t? 

Focus on style, especially tone and voice:

• Are all writers using a consistent voice and tone, or is there wide variation between different writers?

• Are writers consistently using active or passive voice?

Focus on text formatting:

• How are specific formats--like bold or italics--used?

• Are they used consistently across content?

And focus on terminology:

• Are writers using product names correctly and consistently?

• Are they spelling and capitalizing product names properly?

• Are there any terms you don't think writers should be using at all?

Don’t reinvent the wheel

Deanna's second tip on creating your own style guide is: don’t reinvent the wheel if you don’t have to. There are plenty of resources you can use to help you stand on the shoulders of giants. Use templates to save time and get started, and modify them as necessary to meet your team’s needs. 

She uses the template from the Good Docs Project to help her write her style guide. There are sections for a glossary of preferred terms, inclusive language and topic types and templates.

Get team buy-in 

Deanna's third tip is get team buy-in as soon as possible.

Present the results of your content gap analysis with your team members, such as developers, product owners and managers, and other stakeholders. Point out areas where documentation needs consistency. 

Ask if there’s anything you could add to the style guide that would help your team members write consistent technical content. You want to provide a style guide that’s helpful to them, and is it a great way to get ideas that you haven’t thought of. Deanna's style guide was received very positively and she got ideas she hadn’t considered for herself. 

Hold regular planning meetings with the folks who are involved in your style guide. Do deep dives into style guide content, and receive iterative feedback as you develop your style guide. Figure out what voice and tone you want to use in your documentation. If something changes while you’re developing your style guide you can include the information in your style guide. 

Use existing tools

Deanna's fourth tip is to build your style guide with tools you already have. Initially, Tech Elevator had a handbook in Google Docs, but the team rarely used Google Docs, so they also rarely used the handbook. She moved the handbook from GoogleDocs into VuePress, a tool they user much more frequently. It was quick to update and edit, easier to track revisions, and in an accessible location. 

So when it came time to think about where to put the style guide and what to use to build it, VuePress was the obvious choice. Using tools that are familiar streamlines implementation and helps get team buy-in, especially the more senior team members. 

Rome wasn't built in a day

Deanna's fifth tip is that writing your style guide will take longer than you think, and you need to plan accordingly. She thought it would take 3 or 4 months but it’s actually been more like 8 months. It might take a year to get it finished. Based on her experience, some factors that might lengthen this amount of time can include:

• All the people who need to be involved in building the style guide. Multiple departments and people from each department may need to be involved, all of which can add time.

• Your own workload. Oftentimes we don't have the full bandwidth we'd like to throw at these projects, and that's something to be mindful of.

Deanna advises that you shouldn't be afraid to overestimate how long you think completing the style guide will take.

Final remarks

These tips are all solid and actionable, and as Deanna noted, if you keep these things in mind, building a style guide on your own isn't impossible.

We'd probably extend her suggestions to other types of company-wide handbooks that require one person to write/own a project but also require input from a variety of sources--many of these tips would apply well in those situations, too!

Watch the full talk here. 

{{snippet.authorCatherineHeath}}

{{snippet.Disqus}}