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 with AP Stylebook or 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.

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 the focus in this style guide for style guides, how your documentation is organized and the ease in which your readers can 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.

Style for developers

Developer documentation often have a specific set of rules in order to best meet their needs.

Code samples

Here are some example guides for code samples

API documentation

Clear, well-formated, and detailed API documentation is the key for developers to quickly consume and implement your API. It is also key to helping developers understand what happens when an API call is made, and in the case of failure, understand what went wrong and how to fix it.

From the perspective of a user:

If a feature is not documented, it does not exist. If a feature is documented incorrectly, then it is broken.

The best API documentation is often the result of a well designed API. Documentation cannot fix a badly planned API, and it is best to work on developing the API and the documentation concurrently.

If your API already exists, automated reference documentation can be useful to document the API in the current state. If your API is still being implemented, API documentation can perform a vital function in the design process.

Documentation-driven design

If your API still has to be built, you can create API documentation to help with the design process. The documentation-driven design philosophy comes down to this:

Documentation changes are cheap, code changes are expensive.

By designing your API through documentation, you can easily get feedback and iterate your design before any development has to happen.

Some API documentation formats have the added benefit of being machine readable. This opens the door to a multitude of additional tools that can help during the entire lifecycle of your API:

  • Create a mock server to help during the initial API design
  • Test your API before deployment to ensure that the API and the documentation matches
  • Create interactive documentation that allows developers to perform demo requests to your API

Test-driven documentation

Test-driven documentation aims to improve upon the typical approaches to automated documentation. It allows you to write the bulk of the documentation by hand while also ensuring its accuracy by using your API’s tests to generate some of the content.

Projects such as Spring REST Docs use your API’s tests to generate small snippets of documentation that can be included in hand-written API documentation. The accuracy of the documentation is ensured by the tests – if the API’s documentation becomes inconsistent with its implementation the tests that generate the snippets will fail.

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.

Accessibility resources

Relevant talks from Write the Docs:

Content guidelines

It’s important to create consistency in your content types. This allows you to manage your audience’s expectations for what they will learn on any given page.

FAQs

Frequenty Asked Questions (FAQs) exist to educate and guide users through need-to-know information, pointing them to additional resources when necessary. FAQs should be short and limited.

Effective FAQ pages accomplish the following:

  • Reflects the audience needs. This may be derived from understanding search results which lead to the website or documentation.
  • Regularly updated to reflect the changes in user behavior and data.
  • Drives users to different parts of the website to deliver more detailed information.
  • Cover a broader range of topics that may not otherwise warrant individual pages or pieces of content.

Release notes

Release notes exist to provide users with vital information needed to continue to use and benefit from a product, often as it relates to new or updated feature releases. These notes should be brief, linking out to more details as necessary.

Consider the following when creating an entry for your release notes:

  1. What is the change/release?
  2. Why did we make this change? Why is it important to our users?
    1. Improvement in workflow or UI
    2. Consistency/feature parity
    3. Expected revenue increase/decrease
    4. Change in phase: Alpha/Beta/GA (Does this need to be called out?)
    5. Policy/legal changes
  3. What is the goal for our users who use this feature?
  4. When will this feature be available? Is it already available or coming soon?
  5. Do our users have all the information they need to move forward?
  6. Is there an additional article for users to read to learn more?
  7. Would an image be beneficial to help users understand this release?
  8. What stakeholders have to approve this content? Does it require the legal team’s approval?

Some example release notes:

Related talks:

User Guide / Manuals

Tutorials / How-To

Concepts, Overview

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.