Note: This post is intended for non-writers who need to write help documentation. However, most content creators can benefit from the advice here!
In a previous post, I mentioned that you need to create style standards for your help content sooner rather than later. The big takeaway in that post is that style standards breed consistency, and consistency makes your content more helpful, scalable, and trustworthy. This post assumes that you don’t have a marketing or documentation team, and that you don’t have any explicit style guidelines.
In this post, I outline the basics of getting your own style guide up and running.
take stock
The first step to create a style guide is to take stock of what content you already have. You can do this with a content audit. Although you don’t have to do a full content audit, it can save you work down the road. I talk about the benefit of full content audits in this post about my first year as a writer.
During the audit, pay attention to what your content says, how it’s saying it, and how it’s formatted. Start taking notes. Here are some things to look out for:
- Do you use H1 or H2 for top-level headings?
- How do you refer to your product, services, or components?
- How do you write words with multiple accepted spellings? Is it dropdown or drop down, or drop-down? Is is clickthrough or click-through?
- Which verbs are you using for actions? Is it navigate to or go to? Is it enter or type?
Once you’re done with your audit you should have 3 things: a list of your content, a grasp on your organization’s voice and tone, and an idea of how inconsistent your docs are.
decide how you want to say things
If you don’t already have brand guidelines that outline your organization’s voice and tone, you should start there. Voice is your organization’s communication style or personality. Tone is your content’s mood. Tone should adapt to what kind of content you’re creating. For example, your marketing content might have a more exciting tone than your help content.
You can find your voice by asking If our brand were a person, what would they be like? Is your brand bubbly, friendly, droll, or sarcastic? Find it and go with it – write down a paragraph with a few adjectives that describe your voice. For example:
Our brand is bubbly and informal, but not too zealous or too chummy. Our brand is an expert in our field, but is never condescending.
Bam! Now you’re ready to move on.
If you still have no idea what I’m talking about, MailChimp has an excellent guide to voice and tone.
make a list
The next step is to create an alpha list (sometimes called a word list). An alpha list is essentially a dictionary for your organization. It should be part of a comprehensive style guide, but it’s nice to have a separate list that you can use as a quick reference.
This is where you decide how you’re going to write your product components, services, team names, and so on. Creating this list will go far in keeping your docs consistent.
Your alpha list can be as simple as a Google Sheet – just type the word as it should be used. For example, if you’ve decided that dropdown is the spelling you’re going to use, write it down!
write the style guide
The quickest and easiest way to do this is to take a popular style guide and modify it for your own needs. For example, you can use AP Style, but modify it to use serial commas (you should totally use serial commas, you savage). If you want to start from scratch, here are a few questions to get you started:
- How will you write out dates, time, telephone numbers, website URLs, or email addresses?
- Are you going to allow e.g, i.e, etc, or should you use something like for example and and so on?
- How about acronyms, abbreviations and initialisms? Are there cases where using these is okay?
- Will you use logical punctuation or traditional?
Ask yourself a slew of questions, and then write it all down.
If you’re totally overwhelmed already, just borrow someone else’s style guide. MailChimp is particularly gracious and invites you to adapt their style guide.
write article content standards
Here’s where the real help docs stuff comes into play. You need to explicitly describe how each article should be structured and the kinds of content they will contain. You can ask a few questions to get started:
- What kinds of articles will you need? How tos? References and glossaries? FAQs? Think about the types your readers need. A good basic starting point is concept, task, and reference:
- Concept articles give a broad overview of a concept.
- Task articles contain instructions for doing something.
- Reference articles contain more technical content like definitions and specifications.
- How will you write out navigation paths? Will it be Navigate to Home > Settings or Go to Home, then click Settings?
- What will your article naming convention be like? Should task articles be named How to do the thing or Doing the thing? Should FAQs be named xyz FAQs or xyz Frequently Asked Questions?
Figure out your needs, and then write down the rules.
Note on task steps: Steps that should be done in order should always be numbered lists. Avoid using numbered lists for anything that isn’t a task.
keep it updated
Your style guide should be a living document – don’t go through the trouble of creating one and then let it gather dust. Your guide should evolve as your organization does. A well-used and maintained style guide will help keep content consistent and on-brand.
