The style guide struggle is real: 5 things I’ve learned while trying to create one from scratch
During my first week as the new — and only — UX writer on the product design team, my manager asked me if we could “have a content strategy by the end of this quarter?”
I looked him square in the eye and said “Yes.”
I had no idea what he meant.
I just said yes to avoid looking like an idiot. We agreed that a good place to start would be a style-guide-sort-of-thing, and I thought “Oh, yeah, cool. Easy.”
It was not easy.
I spent the next few months (twelve of them, to be exact) looking at other style guides, getting overwhelmed with where to start, and what to include, learning about best practices, asking my manager for more time, answering style questions from my head, getting caught contradicting myself, promising everyone a style guide is in the works, but struggling to deliver while still having to manage the daily writing that also needed to get done.
Now, I am not here to tell you that it gets easier, or that I have fool-proof tips for a smooth sail to Style Guide Island. I can’t show you how to create a style guide from scratch, but I can share the things I’ve learned while attempting to do just that.
1. Have a plan
This one sounds obvious, but it’s so easy to get lost in all the different elements and sections to include that it can become really crazy, really quickly.
Start somewhere
Decide what sections you want to include, and roll them out progressively, in stages, prioritising your roadmap based on your product and design requirements. I know you might want to add everything Polaris has at once, but that was a project that took many months, and many people. Spread out the work, and tackle it section-by-section. Check in with your manager frequently, and bonus points for sharing your progress with your broader team or stakeholders as you go along. Then just keep adding and iterating, forever.
Don’t reinvent the wheel
Luckily, thanks to Polaris and other awesome style guides like 18F, Mailchimp, and Microsoft, a lot of the work has been done for you. Look at as many different style guides as you can, and take from it what you need. The reason best practices are “best” is because they’re widely used and familiar to users. There’s really no need to start entirely from zero. Take the parts that you agree with, and adapt it to suit your own product’s style and tone.
Consider the role of content in the design system
As you develop your style guide, think of how the content fits into the company’s broader design system, if one exists. We often think of the content guidelines as one thing, and the design system as another, but we’re doing ourselves a disservice by allowing them to evolve independently. It only reinforces the notion that design and content are two separate parts of the design process, and I bet we’re all tired of telling everyone it’s not.
By allowing our content guidelines and design system to evolve independently, we’re reinforcing the notion that content and design are separate parts of the design process. They’re not.
Reach out to the designers and developers in charge of the design system, and ask them to show you what they’re working on. Find the components that will contain content (banners, buttons, dialogs, headers, lists, forms, etc.) and consider the guidelines for each.
Atlassian, Polaris (again), and Material Design all consider the content guidelines or messaging of each component, making it clear that content and design always go together.
If your team does not have a design system, start including component-level content guidelines straight into your style guide, under their own sections.
Have a system for making decisions
To make sure that the rules or guidelines that make it into the style guide are not just one person’s subjective opinion, do your homework. Root your decisions in a broader strategy, derive them from best practices, evidence, and research, and check that they’re aligned with your organisation’s values and principles. This not only helps you to make solid choices (and trade-offs), but it will also help you to explain these choices to others.
Check out Content Design London’s Readability Guidelines project for evidence-based style guidelines.
2. MVP, ASAP!
When working on something awesome, we often tend to wait until it’s done, or even perfect, before revealing it. This is not that kind of project. Aim to get a useful, usable version out the door as soon as possible. You can add the fancy stuff later.
Get the basics down first
Most of the time, people just want to know “How do we write the date, is it day then month?” “Do we write out numbers or use numerals?” “Do we capitalise feature names?” “Title case or sentence case?” so start with that.
Most of the time, people just want to know the basics. Aim to get a useful, usable version of your content style guide out the door as soon as possible. Add the fancy stuff later.
A Google doc is just fine
Don’t stress too much about the format in the beginning. A Google, Word, or Dropbox doc is perfectly fine. As long as you can organise your sections, update it, maintain it, and collaborate with teammates.
Help others help you
I know it’s incredibly difficult to build a style guide in parallel with all the actual content writing that needs to get done, but if you don’t start now, you’re going to end up with massive content debt later. Plus, the sooner you put out a style guide, the sooner you empower others to do some writing, which in turn lightens your workload.
3. Remember who it’s for
The style guide is a strategic piece of content that also needs to follow the principles of good design, and good writing.
Keep the reader in mind
The people who end up using the style guide might not all be UX writers, or content strategists. If your style guide is written in a clear, useful, and inclusive way, you might find that it’ll be handy for the marketing team, the internal comms peeps, and all sorts of technical documentation that product managers and engineers like to get stuck in.
A clear, useful, and inclusive style guide should benefit writers, designers, marketers, translators, internal comms, product managers, engineers, and everyone in between.
Follow your own rules
Pay attention to the details within the style guide itself. Make sure you actually apply all the correct guidelines, and add a little flavour to the document by writing it in your organisation’s voice and tone, too. Slack, Microsoft, and GO-JEK do this really well.
4. Tell everyone, all the time
You know when you’ve made up a really good joke and you tell it to a few people, and soon enough, someone tells it back to you? That’s what we’re going for here.
Talk about it constantly
It’s really important that you don’t get tired of talking about the style guide. Whenever someone asks a content style related question, resist the temptation to answer them immediately, and rather direct them to the style guide. Open it mid-critique to settle a disagreement (or admit that you still need to work on that part). Take it with you to the water cooler. Share it on the Slack channels. Have progress update sessions with your team. Hold workshops to discuss and debate the content rules. Just don’t stop talking about it.
Share it, get feedback, update it, rinse, repeat
Remember that you’re building this for people to use, and to do that effectively you’re going to need their feedback. The more eyes you can get on the style guide, the better the end product will be. Just make sure you have a system for making decisions about what needs updating and what doesn’t.
The biggest mistake you can make is to assume anybody knows your style guide exists. Tell everyone. All the time.
5. Whatever you do, don’t go at it alone
Being the sole person responsible for saying whether to capitalise this or that, or to use punctuation here, but not there, or to come up with new feature names, is a tough task. Unbearable, even.
As mentioned before, many others have done this before you. Learn from them. Involve your team, your manager. Involve other teams. Ask for input and opinions. People tend to care more about something when they can see their part in it. So round up a few trusty collaborators, and make them care.
In summary
The style guide struggle is a very real one, but it’s not an impossible task. It just takes some planning, commitment, collaboration, and a whole lot of noise.
That said, Steve Howe has an interesting article full of things you might want to consider before you start writing your guide, and “save yourself the finger cramp.” Best to look at this thing from all angles.
This post is an adaptation of a webinar I hosted with UX Writing Hub’s latest batch of students, a.k.a our future UX writers. Go check out their online course!
