This text was the basis of my recent talk at Write the Docs NA 2018, mostly about the glory and greatness of creating your own style guides from scratch. It highlights some of the major lessons I’ve learned about writing style guides, because I really like style guides — like, a lot. I make style guides for my own personal projects which only I will ever work on. I also help make style guides for wider use, including The Responsible Communication Style Guide. My current project is a style supplement for people writing about the Python programming language, so you will almost certainly hear me complaining about disambiguation if you run into me in person.
I believe I’m among fellow style-guide enthusiasts if you’ve read this far, but let’s just go over a couple of givens for this article. First, style guides are amazing. They’re basically lists of style decisions your team needs to stick to while working on a project that you no longer have to keep in your head. When you’re writing with a team, sharing a style guide will help ensure you all write with a similar style. Readers won’t get confused by different spellings, editors don’t have to correct the same errors over and over again, and writers can eliminate internal debates about when to capitalize the word “internet”. Style guides aren’t limited to written content, either — there are design and coding style guides as well.
It’s easy to build up a whole bookshelf of style guides. There are references like The Chicago Manual of Style, industry-specific style guides like The Bluebook which covers legal documents, organization-specific style guides like The Microsoft Manual of Style for Technical Publications. Depending on the project you may need more than one style guide — you might use an internal style guide when you’re writing documentation, then need to grab something broader to look up what your internal guide doesn’t cover. Sometimes you may need to even pull a more general guide off your shelf, like the Chicago Manual of Style. It’s a somewhat graceful deprecation, keeping the guidelines we need close at hand, with a fallback plan for anything an internal guide doesn’t cover. Those internal style guides are mostly what we’re talking about here — though I still have more space on my style guide shelf if any of you are thinking about something bigger.
Making your own style guide is a relatively easy process. RCSG started as a list of notes I kept for my own writing and then shared with a couple of other people as a template to adapt for their projects. That list turned into a book because it just kept getting longer. You too have the power to create your own style guide deep inside of you. I have faith in each of you.
A lot of developing a style guide is exactly what you think it is. You make a list of what you want to cover in your style guide, maybe words that you need to make sure you capitalize correctly or a list of the colors you should avoid for buttons. You keep adding things when you hear a new suggestion or make a novel mistake. Personally, most of my style guides are just a list of errors I’ve already made and reminders to not make them again. Seriously, I’ve already got a list of errata to update for the next printing of the RCSG because I’ve made new and interesting errors since the book went to the printers.
You edit your list, realize you’ve missed some things, edit again. You ask some people to read it and give you feedback, then you incorporate that feedback. At some point, you’ve got something you’re ready to share with a broader audience. Consider that version a first edition, because style guides are not carved in stone. You’ll start a list of things you want to update in the next version the moment you print a single copy, too. It’s not too different from other process documentation.
There’s no secret sauce when it comes to creating a style guide. You make the tool you need. There’s no magic software that will automagically pluck words from your documentation and shove them into a style guide. You can get the job done in a text file if that’s the only software available to you (though I encourage you to learn from my mistakes and move your style guide out of your word processing software of choice before it’s longer than five pages). A style guide can live within your other documentation or be available separately, depending on what you need.
The mechanics of putting together a style guide probably already feel familiar and I don’t want to spend too much time on them. Let’s talk about the major issues that come up when creating a style guide instead. There are three key sticking points we’re going to cover here:
- Questioning assumptions
- Bringing in unheard voices
- Providing tooling and education
Question your assumptions
Sometimes I think that writing documentation is just a constant process of asking people to break down one step into smaller and clearer pieces. Everyone assumes that certain knowledge is universal. But unless we can develop species-wide telepathy, we can’t make that assumption. Every reader who looks at a piece of documentation brings their own experiences to interpreting it and may interpret it in an entirely different way.
That’s doubly true when working on a style guide. We can’t assume how other people use language. Consider the word “literally.” When I tell you that I am literally freezing, you know I’m cold. But am I actually literally experiencing a concerning drop in my core temperature? Not so much.
Despite my own feelings on the interchangeability of the words “literally” and “figuratively”, we haven’t just suddenly agreed to switch the meaning of a word out of nowhere. Different communities use different words in different ways. Language grows and changes to cover new concepts constantly, like how the word “computer” used to refer to a person making calculations, but now refers to a bunch of different types of devices. These changes are routine, through conversation, slang, academic use, memes, translation and literally every other time we communicate.
We can’t assume we know what someone means when they say “literally” anymore, at least without context. We need to ask.
I would go into a whole bit about user research here, but Jen Lambourne already said everything I was going to say, plus quite a bit more, so I’m just going to refer you to Jen’s talk at Write the Docs 2018 and keep talking specifically about style guides.
Ultimately, the more you can question your own assumptions around the meanings of the words you’re trying to define, the better equipped you’ll be to create style guides that speak to everyone. Jargon, acronyms, idiom, and slang may all have their place in writing — especially within technical writing — but only as long as they improve our ability to communicate.
Examine the status quo
That’s a side benefit of creating a style guide to share with other people, by the way. To create a good style guide requires asking questions about the status quo. If your documentation is all in advanced technical jargon, developing a style guide is a chance to ask why. If there isn’t a reason, style guide development will also offer an opportunity to make some changes to the way your organization communicates.
Many people won’t argue with a style guide once it’s established. I would never encourage any of you to use this fact for evil. For good, though? It’s an opportunity to advocate for changes to the status quo. When you’re making or updating a style guide, you get to choose whether to capitalize the word “Internet.” You also get to choose how members of your organization refer to people, what metaphors are considered inappropriate in your materials, and whether images must have alt text tags. Each of these decisions is an opportunity to create a more inclusive organization as much as a way to coordinate the voice of your organization.
Of course, you should go through all the appropriate approval channels before implementing a style guide, and of course, you should work with your team to make sure decisions are acceptable to as much of your organization as possible. You can adapt and update your style guide as appropriate for your organization.
But that one dudebro in your office who refuses to give you input during the process and then wants to know what they can do to change the whole style guide after the fact? Yeah, for that dudebro, your style guide has already been sent out to be chiseled in stone. Sorry, dude.
I should also warn you about the danger of swinging too far in the opposite direction. While requiring writers to match an organization’s voice and style makes sense, style guides are not meant as ways to police other people’s tone or voice. There is no one true way to write in English and we should only attempt to describe how to use language in our own context. We need to empower writers to do better. It’s never our job to tell people they’re writing incorrectly At best, I’d consider any attempt to enforce particular ways of writing or speaking to be classism. At worst, doing so is a well-established and particularly destructive method of colonization. It also results in bad writing.
So, yeah, writing a style guide is more responsibility than it might look on the surface. Pulling together lists of words and styles isn’t nearly as hard as understanding the impact of a style choice. We have an obligation to take extra care when developing style guides, especially those intended to be used by a diverse audience. We need to balance the voice of the organization with the voice of the writer. We can clarify how we communicate, without policing other people’s writing in a problematic way.
Bring in unheard voices
Empathy is the best tool we have for building effective style guides. We need a lot of compassion in this process, too. We need compassion for our users — the people who will use this style guide to write documentation — but we also need empathy for our users’ users — the people who will read the documentation our users write. Finding enough empathy may be the hardest part of writing a style guide.
Hopefully, you can find compassion for fellow writers, whether they write documentation full-time or write on top of other responsibilities. To empathize with your readers, you need to make sure that you have an understanding of the many backgrounds your readers may come from. I’m not just talking about understanding if someone has the technical know-how to get through your documentation. I’m talking about understanding cultural context around the words we use and repurpose for technology. I like the example of the Chevy Nova. According to urban sales legends, the Chevy Nova sold poorly in Latin American markets because “Nova” means “doesn’t go” in Spanish. Snopes has disproved this story, but I still use it because all of the actual examples I could use require content warnings.
We’re all aware that listening is a key skill for documentation. We know that we need to listen to as many people as we can who create, consume, or otherwise interact with the materials. But there are still voices we can learn from who we fail to hear. We need to listen to programmers with dramatically different backgrounds. I know how to write for the 20-something dudebro with a computer science degree, but I don’t know if the same materials will work for a single parent trying to learn to code in between taking care of kids. The only way to learn is to listen to people who are not in this room. If we want to build a truly inclusive industry, we need to meet the needs of people who haven’t been able to join us yet. We need to go out and find them.
You won’t be able to ensure your style guide is all things to all people. Starting with the intent to listen, and iterate on feedback on as it comes in is the right place to start, though. Include the people you already have access to — as many editors, sensitivity readers, beta testers, and users as you can practically manage — and build on that base to include new voices as you find them.
Pro tip: Inclusion during the development process also gives other members of your organization a sense of ownership and improves the likelihood they’ll use your style guide when it’s complete. It’s nice when doing the right thing makes your life easier.
Empower community members
And, of course, what’s the point of a style guide that no one uses? I feel like there should be a good punchline here, but there’s not really a joke. There’s no value in a style guide no one will use.
The best style guides empower their users. In my ideal world, I could hand anybody a style guide and some workflow documentation and they’d immediately be able to contribute to a writing project. That might be a little utopian, but it’s not as far off as you think. Consider Wikipedia. The site’s Manual of Style is somewhat buried, but the editing FAQ is a mini-style guide, covering things like link formatting and how to write article summaries. It’s more than enough to get someone started on their first Wikipedia edit. The Wikipedia Editing FAQ is a gateway style guide. It empowers people to make immediate changes.
Honestly, you’ll know your style guide is top-notch when someone outside of the docs team can hate-edit inaccurate documentation without needing to talk to an editor. I can tell you from experience that most style guides and contributor onboarding systems are not at this level.
Provide education and tools
Ultimately, a style guide should democratize the writing process in your organization. Style guide users should be able to write more clearly without relying entirely on editors or experts.
That’s a big “should.” There are a lot of assumptions there — and since we’re questioning our assumptions, we need to unpack that “should.” All other things being equal, a style guide should democratize the writing process in your organization. Those other things are the tricky part, though. We can’t just hand people a tool and assume everything will be fine. We need to educate our communities on how to use those tools.
Planning for education needs to be a part of your style guide development before you ever look up your first acronym. For experienced documentation writers, that education may mean a short workshop on the specifics of *this* style guide, while other users may need more of a “Style Guides: How do they Even” class. Ideally, someone should be able to pick up a style guide and use it without a class but given that very few people seem to read style guides all the way through, personal walkthroughs is a really good idea.
I like to start my educational plan with materials on how to contribute to new iterations of the style guide, by the way. The more people who can add to and improve a style guide, the more the workload is spread out, which isn’t exactly altruistic but is a necessary practicality.
If you can create a culture of contribution for your style guide from the start, you’ll enable improvements you can’t imagine ahead of time. Go beyond writers, too — if you’ve got a developer who needs to write at least some of their own documentation, giving them access to your style guide files can let them build tools that work for them (and that might work for you, too).
Don’t fall into the trap of thinking of a style guide as a book or a handout. Digital style guides put information in a wider variety of hands and create a world of potential right now, from providing a basis for new kinds of linters to upgrading spellcheck to something far more useful. Imagine how great the future will be if we make all of our style guides available via API!
Move the Overton window
Style guides represent the future, whether we know it or not. They streamline production processes and give people power to work on their own projects.
They also give us the opportunity to talk about how we write and why. Those discussions have the power to change the world. Style guides offer a clear indicator of how an organization wants to discuss different questions. A style guide that cautions users against terminology that some readers will find offensive is an explicit Overton window. An Overton window is a guide to what we consider appropriate to share in public discourse. For example, women wearing pants in public was considered highly inappropriate — until the Overton window moved as more and more people decided pants are perfectly reasonable apparel.
Our communities, both technical and not, are facing big questions about what we want to look like in a year, in five years, in ten. Within technology, many of these big questions are about inclusivity. Some communities have hard-coded styles of communication that exclude everyone who hasn’t personally written a programming language. Some communities want to make sure that the benefits of technology are available to everybody. The ways we style materials dictates, in part, what side of the divide our organizations land on. The more tools we have to create inclusive documentation and other materials, the faster we can move the Overton window towards expectations of respect and inclusion, at least within our own organizations.
I’m not expecting anyone to go back to work just to lead a style guide based-revolution (though if you want to, I’d love to hear about it). I am hoping, though, that you’ll start thinking about how you style your own work and whether a style guide will help your organization communicate more effectively.
I’m hoping you’ll think about the cultural assumptions that go into a style guide and how to give a voice to more people in your organization.
I’m hoping you’ll think about the communication status quo on the projects you work on and whether that status quo is effective.
I’m hoping you’ll drive big conversations about the future of our communities and how to welcome more people to those communities.
To sum up: style guides are awesome.
You should make at least one style guide in your life, if only so I have more people to commiserate with, I mean talk shop with.
When you’re making style guides, consider the assumptions you make, how you can empower the people who will use your guide, and what you hope the future brings, at least in terms of communication.
Lastly, making a style guide is an awesome responsibility. It gives you the opportunity to guide conversations, defeat miscommunications, and maybe even inspire newcomers to your communities. Subtle, yes, but style guides are powerful — and with great power comes great responsibility.
You can watch me give the original version of this talk at Write the Docs here, with bonus digression into why peanut butter isn’t the All-American treat we think it is.
You can buy a copy of The Responsible Communication Style Guide here.
