You Need a Style Guide

When you're first getting your docs up and running a style guide may seem like a nice-to-have at best, a hassle at worst. Maybe it's something you're considering adding down the line, or perhaps you're a lone-writer, and it seems totally unnecessary.

I've thought all those same things before! The longer I write, though, I've realized how invaluable style guides are, even if you're the only one using it.

Here are my top four reasons.

1. Style Guides Are the Key to Consistency

Consistency can be the difference between crystal clear docs and docs that leave a user slightly befuddled. Say you refer to a feature as 'Deus' on line 1 and on as 'Deus Ex Machina' three paragraphs later. Internally, this isn't a problem at all! Nine out of ten readers might not even notice the difference.

But as documentarians, that one out of ten should be top of mind when writing.

They're also going to be most confused about it if something else is going wrong.

"Oh, I got an unexpected error? Maybe I was actually supposed to put that into the Deus section, not the Deus Ex Machina section. Hmm, I must be doing something wrong. Let me CTRL-F this and see if I can understand it better."

In a style guide, you can list out the preferred product name and variations to avoid.

(This isn't to say that you can never very. Sometimes it's appropriate—in marketing content, for instance.)

This may seem innocuous, but it can become a big problem if they're running into any other errors throughout the process.1

2. Style Guides Saves Time

But Linda, what about the time it takes to write a style guide? We're strapped as it is, and I can't take time out to list out every little thing we need to do, let alone take the time to look it up.

Well, I have two responses to that. First, no, you definitely shouldn't pause writing to look things up. (I recommend establishing a system.)

When style guides really start to shine is during the editing process.

Rather than having to trust your own judgment each time (it's shocking how often a single writer can change their mind) or scrolling through the document to check what you did last time you can simply check the style guide.

3. Makes Your Docs Scalable

You won't be the only one using your style guide forever. As your docs grow, hopefully so will your team. Having an established style guide will make it simpler to onboard new writers, and keep consistency as your team grow.

(If you're a small company just hiring your first dedicated writer, consider creating a style guide while you're searching for your perfect hire.)

4. Style Guides Are Enforceable

Once you have a style guide, say goodbye to debates about whether to use the oxford comma. It's in your style guide!

Depending on your toolchain, you can also enforce your style guide automatically. (Think, linters.) Just like coding linters, text linters can remove the need to manually correct mistakes, prevent mistakes from getting published and generally speed the editing process.

Other Notes About Style Guides

A Style Guide is Just a Guide.

Remember that a style guide is just a guide, not a set a commandments. Its purpose is to make your writing easier, faster and more clear. As the writer, you have the ultimate authority to decide what works best for your documentation.

OAS Specs also Need a Style Guides

Any descriptive text in your OpenAPI spec can benefit from being run through your style guide. There are also additional guidelines you can include in your style guide that apply only to you OAS spec, including:

• Whether descriptions end with a final period
• How to format summaries
• How to reference other endpoints
• And more

Create a Style Guide as Early as Possible

When your first starting your docs, start by choosing a fallback style guide. This is the style guide writers should defer to if your style guide doesn't have specific rules. As the writing process continues, you'll add more rules to the style guide and adjust as needed.

A great time to formalize your style guide is after you have an OAS spec and a few guides, but before hiring your first dedicated writer. They can adjust as needed, but giving them a baseline will speed up their training process immensely.

Need Help Creating Your Style Guide?

Let me create a style guide for you! It's an investment that will pay dividends in your documentation for years to come.

Check out my services page for pricing or contact me directly with any questions.