I've used and perused style guides most of my career but hadn't found myself in the position of creating one until last year. I got super acquainted with style guides in 2016—I wrote one for my employer, I referenced a publisher's style guide when I copy edited one of their books, and I contributed to one.
In my career, I've always looked at style guides with a sense of awe. Some of the best-known style guides—think AP stylebook or Chicago Manual of Style—are downright prolific, and considered industry standards. But companies with a strong sense of what branding means have created strong style guides that have helped them distinguish themselves from others, like Slack and MailChimp.
Style guides are useful, indeed, but what if you don't work at a large company, or what if you don't produce a lot of content? Or what if you don't see yourself as a brand? I work at a small dev shop that services large clients, or at a small, 20-person startup building developer tools. I'm a software developer with a small blog. Do I need a style guide?
Before I answer that, allow me to share a story.
Like documentation, but for human languages
When I started working for my current employer, we were just under a hundred people. I was the first person ever hired to focus on copywriting, and at the time that meant touching both marketing and product copy (I have thoughts about why this is not a good idea, which I'll share in a future post). With other teams in the company also producing their own external-facing copy, like our support team, I naturally got involved by helping them by writing new content and editing existing content.
As it turns out, I love love love organizing things and creating processes, so I created templates for just about every type of asset I produced and have saved them for future reference. This system worked in the beginning and I'd intuitively understood the company voice and memorized (read: for the most part) grammar rules we used in-house. I thought this was enough.
But organizational growth meant working with more and more people, and I was getting pinged a lot with style questions, like:
- Capitalization. Is button text capitalized? Do we capitalize specific words?
- Spelling. Is e-mail or email? Internet or internet?
- Punctuation. Do we use the Oxford (or serial) comma? What do we do with emails riddled with exclamation points?
- Voice. We're sending an email to VIP customers. This is a template we've used in the past, and we just changed the details. Is this on brand? (Receives a draft full of exclamation points! Letting! The customer! Know! We're so! Excited! And happy they! Do business with us! And it's signed, "With Love, XYZ Manager".)
I was finding that, after a point, I was forgetting my own rules. It was just too much. And beyond that, what if we hired a new writer on my team? How would I communicate the rules to new people?
What did these issues actually look like IRL? Well...
Inconsistent capitalization in buttons and headers across our website and landing pages
Inconsistent spelling of industry-related terms and even company names
Inconsistent formatting in subject lines and signatures in emails
Different tone of voice employed in certain emails and "plain English" section in our Terms of Service
(Story within a story: While rewriting the "plain English" sections of our Terms of Service, I learned that a few people were really mad at the changes I was making to the tone. Why? Because their opinions of the organization's voice and mine were totally different. They were used to the voice the organization used when we were still very small, but I reasoned that our voice had changed to reflect we were a growing organization with customers from all over the world. That voice—and the language we were using—didn't translate well and could be off-putting. In the end, my argument won out, but it further illustrated the need to have these things agreed upon and documented beforehand.)
It was becoming unwieldy. As time went on, more and more people in the organization were writing their own content for different reasons. I couldn't QA everything and needed a resource to ensure that content was treated the same throughout the organization; that people had a reference point to turn to if they were confused about what it meant to write "on brand". I needed to document the rules of engagement and share them with the organization.
That resource, dear friends, was a style guide. I needed one and ASAP.
So if you want to know whether or not your agency or company needs a style guide? If you produce any kind of content that outsiders see—if you have a marketing website, create landing pages for different things, publish case studies, write blog posts, or send promotional or transactional emails—the answer is: Yes. You need a style guide.
What is a style guide?
A style guide is a set of rules and standards that governs writing in your organization. It serves as a single source of truth for how your organization writes. The goal of having a style guide is to achieve clarity and cohesion across all of the different mediums where you produce content. This means if one person leaves, all of that style knowledge doesn't leave with them. Conversely, if your team grows, it means that everyone is poised to write in the organization's style, not based on any single individual's personal preference (Mary prefers "e-mail" and "Internet", but she doesn't change "email" or "internet" when editing someone else's copy; When Alexei was at the company didn't use the serial comma, but since he's left, Emma has introduced serial commas into our copy).
Style guides are best known for things like grammar rules—Chicago Manual of Style, hello!—but they also include things like a glossary of preferred terms your organization uses. If you work in tech, for example, you might already be acquainted with the "master/slave" terminology used in database architecture. For many reasons that I personally endorse, lots of projects have decided to move away from this terminology and have adapted their own terms. Drupal, for example, now uses "primary/replica", terms they've probably added to their style guide. Similarly, you might have spelling conventions that are important for people to know, such as the difference between "login" and "log in"; frontend vs front-end; internet vs Internet, etc.
Why do they matter in tech?
One of the things that surprise me the most is how tech understands the importance of user experience and user sentiment with our products—but not how words play into that. We understand the importance of how a site appears, but we don't always pay attention to what it is we are trying to say.
Words are important! They instruct, they inform, and they persuade. They can assuage your fears or make your blood boil. We communicate with our audience with words.
You can make a beautiful, user-friendly design, but without words, it's all meaningless.
Imagine someone interested in your dev shop's services visits your website....and there are no words. Imagine checking your email app......and there are no words anywhere. Imagine receiving an email....and it's empty.
You get the picture. Words matter.
Consider some ways you interact with words from organizations you love:
Slackbot messages that tell you how to do a certain thing.
An email from an app you use that communicates major changes in pricing.
Emails from the CMS you pay for apologizing for an outage that affected your service, and how they plan to improve so it doesn't happen again.
Pop-up modals in software you use for your designs that show you where you can access new features, and how to use them.
Now imagine a time when an organization didn't communicate something well. Or how they wrote a blog post that sounded either disingenuous or just completely not like them. Or how an organization promoted a pricey product on a site littered with typos, inconsistent casing, and even tone of voice.
Words mean a lot, and our reactions to what we read are sometimes subconscious. Words are important because it's how we communicate online. Unless you're peddling your wares door-to-door and face-to-face, the words on your site are going to be your users'/customers'/visitors' introduction to you and what you offer. You will be making a first impression with words.
No one thinks about how much consistency and clarity matter, but it's how you build trust and how you communicate to end users that you are a professional and you know what you're doing.
In short: a style guide is a form of documentation like any other. Formalizing guidelines early will help you ensure consistency as you scale and as you work with content producers inside of—or consultants hired from outside of—your organization.
Creating a style guide without reinventing the wheel
The first thing I wish I knew before creating my company's style guide is: You don't have to reinvent the wheel.
Depending on the size of your organization, and the number of people working on the style guide, you won't be expected to produce anything as prolific as the AP stylebook, or the style guide of an organization that clearly has a team of writers and editors working on it. I promise.
In order to know what you need in a style guide, it's helpful to know what a company style guide looks like. Thankfully, there are some useful ones out there that are available for anyone to see:
MailChimp Content Style Guide (available under a Creative Commons Attribution-NonCommercial license)
Take a look at these style guides and see what they cover, and measure that against what your needs are. If you don't produce a lot of content or produce very specific types of content, you might find that everything doesn't apply.
What did I include in my organization's style guide?
I used MailChimp's style guide as the framework for my organization's style guide. After studying it and considering our needs, I decided upon the following categories for version 1.0 of the style guide:
Company Voice
Company-specific Terms
Industry-related Terms (we call this the "Word Usage List")
Acronyms and Abbreviations
Capitalization
Currency
Blog
Email
File Extensions
Lists
Numbers
Punctuation
Ranges
Spacing
Links and Resources
The style guide is much smaller than MailChimp's and doesn't follow their formatting exactly. But there were sections that I was able to lift—like those focused on grammar—without making any changes.
Something important to keep in mind is that style guides are living documents. The AP, for example, releases a new edition of the stylebook each year, adding new things and removing others. You can—and should—make changes to your style guides when the need arises. At my organization, plans are underway to make further changes to the style guide. We're even bigger now than we were when I started, and a foundation is easier to work with than starting from scratch. You also don't have to publish it for the world to see; my organization's style guide is an internal resource and it's hosted in the company wiki.
Go forth!
In conclusion, the main reason why software developers who blog need a style guide is to ensure clarity and consistency at every stage. How you communicate is every bit as important from a brand and user sentiment point of view as what you communicate and how something looks. You want everyone in your organization, future employees, and even consultants to know your style so your brand never gets watered down. Communicate the goals of the style guide early on to your employees and any consultants you hire that will be writing, or touching, copy in any way. Show them how to use it and explain how it'll make their lives better. Make it easy to find and take every opportunity to remind people that it exists for their use.
Remember that you don't have to reinvent the wheel and you don't have to produce a body of work for it to be useful. Determine what your needs are right now, and create a style guide that specifically addresses those needs. Iterate on it as your organization evolves. It's easier to work on something that exists while you're small than to build something from scratch when you're much, much larger. Take it from someone who's been there.
Like this post? Purchase The Developer's Guide to Content Creation for more content-related tips and exercises.