Style Guides

A style guide contains a set of standards for writing and designing content. It helps maintain a consistent style, voice, and tone across your documentation, whether you’re a lone writer or part of a huge docs team. It can provide guidelines for different documentation deliverables, such as API reference manuals, tutorials, release notes, or overviews of complex technical concepts.

A style guide saves documentarians time and trouble by providing a single reference for writing about common topics, features, and more. The guidelines in a style guide help writers to produce documentation that has the same tone and grammatical style, regardless of who writes the documentation. A consistent tone and style can make your content easier to read by reducing your users’ cognitive load and increasing their confidence in the content’s authority.

Write your own style guide?

A style guide can be something as simple as a list of decisions you’ve made about how to refer to different items you frequently write about. Or it can be as complicated as the mighty tomes of major publication houses.

You can certainly create a style guide of your own. For the sake of simplicity, this approach might work if you’re a lone writer or just starting a small docs group. But neither software nor its documentation operates in a vacuum, so it’s a good idea to consult other resources as well. Working from an existing style guide can also help you figure out which things matter in your style guide.

Style guide resources

Style guides have been around for as long as people have been publishing in any format. Older style guides originally intended for specific forms of print publication have become basic standards for many others to refer to, including documentarians:

Classics for software documentation include:

Others you might find useful:

Thinking about accessibility and bias

It’s important to consider accessibility and biases in your style guide to ensure that all readers can understand the content you produce.

Writing for accessibility

Writing for accessibility includes making sure copy can be read by screenreaders, content organization, style and color of text emphasis, and more.

Relevant talks from Write the Docs:

Reducing bias in your writing

You can reduce bias in your writing by considering the meanings and origins of your word choices and how those might be perceived or understood by your readers. Even thinking twice about what example user names you include in your documentation can significantly reduce bias in your documentation. Fortunately, resources are increasingly available to help you with this kind of attention to your writing.

Free guides:

Free resources:

Paid resources:

Relevant talks from Write the Docs:

Developer documentation and APIs

Example guides for code samples:

API documentation

Clear, well-formatted, 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 poorly designed API. 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 its 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 isn’t built yet, 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 development begins.

Some API documentation formats have the added benefit of being machine-readable. These formats open 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 content.

Projects such as Spring REST Docs use your API’s tests to generate small snippets of documentation that you can include in the 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.

Content guidelines

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

FAQs

Frequently 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’s 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 related 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 following style guides focus on writing more generally: