Style Guides

A style guide is a set of standards for the writing and design of content, defining the style to be used in communication within a particular organization. Basically, style guides are put together to clarify the way a group of people talk and write about the things they do. Think of authoring best practices.

If you happen to have a background in academia or journalism, you will probably be familiar the AP stylebook or the Chicago manual of style. Those are great resources for writing in general, particularly for grammar and syntax, but if you’re reading this page chances are you are considering style in the context of technical documentation.

Technical Documentation

Style guides help you write a variety of content, such as documenting the methods of an API, or presenting an overview of complex technical concepts, or focusing on how to write particular content like user manuals, release notes, or tutorials.

Guides often help writers focus on the different readers of technical documentation, describing how to adapt content to different reader profiles, like developers, product managers, the general public, and others.

Many focus on the language itself (tone, style, grammar).

Others go beyond the content and discuss the organisation of the documentation, providing best practices on how to manage your content, version control, or publication and delivery strategies. While this is not what we focus on in our style guide, how your documentation is organized, and how easy it is for your readers to find what they are looking for, can be as important as the content itself.

Why do I need a style guide?

A practical reason to use a style guide is that they help you write content. Human languages are extremely flexible, and there are many ways in which a particular message can be communicated. By following a style guide you limit the variation, making it easier for you to focus on getting your message across. This makes style guides extremely useful for people joining projects.

Style guides also increase consistency in your content. There are good reasons why you want to keep a consistent tone, voice and style in your documentation. Marketing-oriented folks understand the importance of voice and tone in building a brand identity, a strategy we can extend into technical writing. Consistency also has a big impact on how effectively you communicate – that is, on how well you manage to transfer a particular information to your audience.

There’s science behind this. Our brains appear to be hardwired to identify differences – anything that stands out from its context will catch our attention. A lot of variation will drain our cognitive resources, making it more difficult for us to assimilate information. The degree to which cognitive resources are drained varies between people, but in general it is a good idea to minimize the cognitive load of your communications.

Different styles for different folk

Choosing the right style guide for your project depends on your particular context:

  • Who you are
  • Who you are writing for
  • What you are writing about

Selecting a good style guide for you

There may already be a style guide somewhere within your organization. It is a good idea to ask your colleagues about this before picking a particular style guide for your project.

Here are some good general resources – perhaps someone in your company is already using one of these:

If you belong to an open-source community or NGO, you can consider the following resources:

Selecting a good style guide for your audience

Technical documentation takes many forms, each one targeting a certain need. Here, we can think of examples like tutorials, API documentation, and user manuals. So while many style guides adequately cover the main concerns of all technical documentation, sometimes a more specialized guide is needed.

Thinking about accessibility

It’s important to consider accessibility in your style guide to ensure the content you produce can be best understood by all readers. Writing for accessibility includes making sure copy can be read by screenreaders, content organization, style and color of text emphasis, and more.

A few great resources:

More info is needed for the following

User Guide / Manuals

Tutorials / How-To / FAQ

Concepts, Overview

Release Notes

API documentation

Writing Style

The style guides below focus on the actual writing craft itself. They consider how to make technical content readable, clear, succinct, and engaging.