Style Guides: Personal and Practical Tips 
on How to Get Started 
and Keep Going

By Karina Lehrner-Mayer | Member

This article provides a practical guide to documentation teams for creating documentation guidelines that are actually used by team members. It helps team leaders and writers who are still struggling in their day-to-day work without a formal style guide to think about starting one. It also includes tips for teams with existing style guides who would like to increase acceptance and use of their style guides.

The article is based on my personal experience when I built and introduced a style guide to a documentation team of 11 writers and reveals what worked and what didn’t.

Do You Have a Style Guide?

In the perfect world of a technical writer, every documentation team or publication department has a style guide that is proudly given to every new writer joining the team. We all know that this world is not perfect and when I joined the documentation team in an Austrian software company almost three years ago, there wasn’t a department guide to turn to.

The reasons why no writing guidelines were in place soon became obvious: All of the writers were too busy with the complex content and the sheer amount of documents that needed to be updated, written from scratch, and maintained, some of them in two languages. No one had the time to do the research such as consulting existing industry standards that precedes the act of writing a rule down. And neither did anyone have the nerve or willingness or patience to write down guidelines.

On my new job, it was clear from the beginning that among writing tasks one of my responsibilities would be creating a documentation style guide (during the job interview I had boldly asked for the team’s style guide). Although a style guide had never been number one on the agenda of writers who were struggling with a heavy work load and faced with complex content and numerous documents, I was going to build one that would make the writers happy. (At least that’s how I saw it.)

If you are in a similar position as I was or, as a manager, wonder if and how to create a style guide, you’ll find helpful information in this article. And if you already have a style guide, read on to find out how to keep it alive.

Before You Start

In my experience, two factors are most important for starting a style guide project: 1) a single person (or, in large documentation departments, a dedicated style-guide team) responsible for the project and 2) support of this person’s style guide activities.

As the style guide supporter, forget all of the historic reasons for why no style guide exists and stress the benefits of creating a style guide. Have arguments ready for all of the things you might hear. For a quick reminder, see the summary of benefits in the list “Quick reminder: Why every team should have a style guide” below and learn it by heart.

There can be only one

There must be one (only one) person or dedicated team that is responsible for the style guide, its content, and updates. It helps if the style guide team member has an eye for details and recoils at the inconsistent sight of user-friendly and user friendly in one document. A neurotic disposition to have everything done the same way and look alike and according to rules is also helpful.

Do you read publication style guides in your free time? If your answer is yes and you are not afraid to enforce a rule, this may be the perfect task for you. If you tend to think of user friendly vs. user-friendly in terms of artistic freedom, you will probably have a hard time seeing the need for consistency and convincing others of it.

Bring the manager on board (if they are not already there) …

It’s vital that the manager and team leaders back up your style guide activities. This does not mean that they need to devote time to formulating rules or taking part in lengthy discussions (because they will have other things to do anyway) but that they will support your efforts. This means assigning you the time to research, write, and communicate style guide rules, as well as standing in when a decision or more information is needed.

The good thing is, the time needed for style guide activities will gradually decrease as the style guide grows and questions are answered. Still, whenever an existing rule needs to be updated or a new rule must be added, someone who is responsible should be able to free some time for these tasks.

… and your co-workers

In general, a documentation style guide helps writers to concentrate on content and not lose time thinking about how to spell or format or phrase something. You cannot stress this enough. Repeat this like a mantra—to the managers and to the writers. Sometimes writing conventions may seem time-consuming and irritating, but in the end the style guide serves only two ends: 1) to help the company sell more products by increasing user satisfaction and 2) to make the lives of the writers easier.

Getting Started

Look and listen, research, write, communicate

A good starting point to build a style guide from scratch are existing industry standards (remember, the books you are reading in your free time), as well as other style guides you have encountered in other organizations. If there is a company style guide or another department’s style guide, take a good look (in my case, there wasn’t one).

When new persons join a team and familiarize themselves with the products and existing documentation, this is also the perfect time to start the style guide. There is a certain period when inconsistencies in style and terminology and other relevant issues stand out. When the person is not new anymore, they are most likely not noticing these things anymore or getting used to the way things are. So, if you are new, get started soon with the style guide. If not, ask people who have just joined your team or another department and use their feedback.

Did you notice any inconsistencies in the documents you have read or taken over? Did you hear any informal discussions going on the hallway between writers about how to spell user-friendly? These are also starting points for your style guide.

And, of course, do not forget the rules that are not broken but complied with and are still noteworthy because they need to be explained every time a new writer joins the team.

Choose your tool and format

It might seem irrelevant whether you write the style guide as a Word document or create it with any other tool. On the other hand, consider the chances you have if you use exactly the same help authoring or documentation system that you use for creating your official documents: you can make the style guide itself an example of a document that follows the rules. The examples in the style guide will look just as they should in the official document, and if something is not working as the rules say (for example, due to restrictions of the documentation system), you will find out immediately when you try it out in the style guide.

Researching

Agree with your manager on which industry style guides to turn to. Do the research alone and present your suggestion (or, if there are more candidates for a solution, make one suggestion your favorite one). Have your answers ready for why you prefer one version over another. There is often no right or wrong and other factors make the decision, such as is a rule already followed by the majority of writers, is a rule accepted by the team, is it easy to follow, etc.

Find your allies

This is not essential, but it can make your life easier. There might be other writers who share your enthusiasm for rules and regulations (well, at least a bit). Turn to these teammates for brief discussions on an issue to be decided. You might also need their backup if it comes to taking a vote.

Decision-making time

As Krista Van Laan wrote, there is more than one right way to do things and sometimes it is a matter of taste which way you go. In a situation where there are two or more equal solutions, I always like to go with the solution that comes with the least effort and works best for the writers. Let the writers and the documents take a vote.

Always involve the team leader and, for sensitive issues, always involve the manager (for example, terminology issues regarding product names and branding are usually sensitive).

Communicating

Even as important as writing a style guide rule is making this rule known to and accepted by all team members. This is where I had to learn the most to find out what worked and what did not. It turns out that a combination of written rules, style guide meetings, short emails, and brief informal discussions works best.

For introducing the first version of the style guide and for presenting new or more complex issues, I found a team meeting with a presentation and discussion appropriate.

For minor additions and to brush up on existing rules, short emails to the team members seem sufficient. I have made it a habit of sending a style guide newsletter, although not each week, but I try to keep it fairly regular.

Also, I try to keep all the rules in mind (or at least know by heart where to find each one) and happily answer any questions that are directly addressed to me.

If you provide a mix of different means of communication, you increase the chances of reaching each and every one of your coworkers.

Give examples

What I hear very often from my teammates is that they want to have each rule illustrated by examples. While the first version of the style guide did not include examples for all the rules, I now make a point of providing useful examples whenever I write a new section in the style guide or send a style guide newsletter. It seems that the examples get the most attention.

Keep the Fire Burning

When you start from scratch, you will spend a lot of time researching and writing and communicating. But as the style guide grows, you will find that you need less and less time for your style guide because the important issues have already been dealt with. Even then, it is essential not to forget about the style guide altogether.

Even when you have your own workload of documentation to do, keep an eye on the style guide and your ears open to discussions. Be prepared to devote a certain amount of time to style guide activities.

Watch out for issues that still come up in discussions between team members even if they are already solved in the style guide. These topics are candidates for a quick reminder, either by email or in a short presentation.

P is for Pragmatic—this is your team’s style guide

I am always open to what goes into our style guide—the writers decide. Even if a topic is not strictly speaking a stylistic one, why not include it in the style guide, as it’s better than to forget about it altogether. Sometimes it turns out that a topic is first dealt with in the style guide and then deserves its own place. For example, we had a terminology section in the style guide that soon outgrew the guide and is now a separate document. Also, when we began to create instructional videos and tutorials, the video style guide started out as a chapter in our documentation style guide.

Based on the individual background and makeup of a team and the specific authoring environments, make this style guide a special, individual one. For example, we have a fast-growing, multinational team with writers from all different kinds of linguistic and educational backgrounds. Although we write documentation in English, there is only one native speaker of English on the team. This is why our style guide also addresses questions of basic English grammar.

Some of our documents are translated into and maintained in German, so our style guide features sections on German grammar and conventions and all examples in the style guide are given for English and German.

Stylistic Pitfalls

Keep it short—don’t provide too much background information

Although you often have to do some research where you consult various industry style guides and collect detailed information, be ready to explain the pros and cons of a specific solution in two sentences.

For example, I had once prepared a detailed four-page document arguing for a rule to solve a certain problem that I (and also the other writers) desperately thought needed to be decided. As it turned out, the manager did not want to read the paper, but a short meeting where I and the team leader presented the gist of the four-page document in a few minutes was sufficient to reach a conclusion.

As disappointing as it sounds for the style-guide writer, managers and other writers are not interested in the research details; they only want a quick and professional solution for their problem.

Keep it small—don’t solve too many topics at once

Break down stylistic areas into smaller chunks. It is much easier to solve little bits one after the other than a huge set of rules in one go. (However, don’t forget to keep the bigger picture in mind.)

For example, we wanted to provide rules for the structure of our documents. As we have several different types of documents, from administrator guides to reference guides to course guides, we started to define the structure for one document type first, then for the next one, and did not do them all at once.

Resistance is futile, or is it? Don’t expect that everyone follows the style guide

Wouldn’t it be nice if everyone happily did as the style guide says? This is rarely the case in a fast-paced documentation world where every writer must meet tight deadlines, focus on complex products, and simply forgets about those rules that mean so much to the person who wrote them.

If you notice that a rule is not being followed and is clearly explained in the style guide (with a lot of examples), it is your job to do something about it.

Do the writers not know about the rule? Send a short email reminder that sums up the rule and gives examples. Does the rule require too much effort and time to master with tight deadlines? Or are there other reasons, such as restrictions of the documentation system, that make it too time-consuming for the writer to follow a rule? Consult with our team leaders and managers on how to address these issues.

Working with Style

Building style guides is fun and a welcome change to writing tasks. It is also very rewarding because you can see the results of your work directly in the documents. The writers, the documents, and the whole company will benefit from a documentation style guide that is actually used. So go ahead and start a brand new one or polish up the old one you have.

Good advice

• Make one person or team responsible.
• For more solutions, present one as your favorite.
• Keep rules simple.
• Be pragmatic.
• Always include examples.
• Communicate in different ways to reach everyone.

Not so good advice

• Try to solve too many issues in one go.
• Present too much information at once.
• Involve too many people in the decision-making process.
• Insert a rule into the style guide and think this is it—the guide is complete.

Quick reminder: why every team should have a style guide

• It helps new writers become familiar with the documentation quickly.
• It is a time-saver—writers can concentrate on content.
• It increases the language competence of the team (if approached by members of other teams on an issue, you can refer them to the documentation style guide).
• It leads to a more professional look of the documents.
• It increases user satisfaction.

KARINA LEHRNER-MAYER (karina.lehrner-mayer@isis-papyrus.com) holds a degree in translation and has over 15 years’ experience in technical communication. She works as a technical writer at ISIS Papyrus Europe AG, an Austrian-based company offering end-to-end solutions for inbound and outbound business communications. One of these solutions is also used as authoring system by the documentation team.