Home » Software documentation guide »

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. A style guide saves documentarians time and trouble by providing a single reference for writing about common topics, features, and more. It can provide guidelines for different documentation deliverables, such as API reference manuals, tutorials, release notes, or overviews of complex technical concepts.

A consistent tone and style makes your content easier to read, reducing your users’ cognitive load and increasing their confidence in the content’s authority.

Structure of this page

  • General style guide information and examples

  • Writing for accessibility

  • Including anti-bias information in style guides

  • Style guides and resources for specific content formats

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.

How-to articles for writing a style guide

Traditional writing style guide resources

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

Additional books on writing:

Sample writing guides

Classics for software documentation include:

More enterprise software style guides

Style guides from government and education

Style guides from open source projects

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. For details, see:

Developer documentation and APIs

Style guide and guidelines for code samples:

Command line resources

A command-line interface (CLI) processes commands to a computer program in the form of lines of text. Style guide standards for command line interface docs and text include these useful CLI resources:

Relevant talk from Write the Docs:

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 API 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.

API resources

Content guidelines

It’s important to create consistency in your content types to manage expectations for what users learn on a given page.

FAQs

Frequently Asked Questions (FAQs) exist to educate and guide users through need-to-know information while pointing them to additional resources when necessary. FAQs are short and limited.

Effective FAQ pages accomplish the following:

  • Reflects the audience’s needs. This requirement may be derived from understanding search results that 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.

Caveat: Be sure to follow a maintenance plan for FAQs, since many content gets parked here and becomes outdated. Consider finding a relevant content structure for the content outside of the FAQ scope.

Release notes

Release notes exist to provide users with vital information required to continue to use and benefit from a product. Release notes content is related to new or updated feature releases. Release 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 specific change?

  2. Why did we make this change? Why is it important to our users?

  • Improvement in workflow or UI

  • Consistency and feature parity

  • Policy and legal changes

  • Security

  1. What is the goal for our users who use this feature?

  2. Do our users have all the information they need to move forward?

  3. Is there an additional article for users to read and to learn more? Yes? Link to those resources.

  4. Would an image be beneficial to help users understand this release?

  5. What stakeholders have to approve this content? Does it require the legal team’s approval?

Release Notes Style Guide Resources:

Examples of great release notes:

What to avoid:

Error messages

Errors in software are unavoidable. Users might click a link that turns out to be broken or they might perform an action only to be met with an unexpected outcome. When a user encounters a problem, it’s important to write error messages in a way that doesn’t alienate the user.

Here are a few tips on what makes a good error message:

  • Provide explicit indication that something has gone wrong.

  • Write like a human, not a robot.

  • Don’t blame the user – be humble.

  • Make the message short and meaningful.

  • Include precise descriptions of exact problems.

  • Offer constructive advice on how to fix the problem.

Related resources: