Style guide

Introduction

{(Before using this template, please read the accompanying About the Style Guide Template documentation.)}

Welcome to our project! This style guide is intended for use by project contributors, not necessarily end-users. It provides general guidance to anyone who contributes to the project's documentation.

Intended audience and scope

This style guide is intended for use by any contributors that are writing documentation for {(Your Project Name)}, including software engineers. This guide can help project contributors to communicate clearly and consistently in {(you define the scope: the project's end-user documentation, API documentation, forum posts, and so forth.)}

Our preferred style guide

We have adopted the {(your preferred style guide, such as the Google developer documentation style guide)} for {(Your Project)} documentation. For a quick summary, see the Google style guide highlights. The rest of this document describes our project-specific customizations to {(Google's or your preferred)} guide.

Our project uses {(your choice: standard American spelling or standard British spelling, etc.)} and our preferred dictionary is the {(American Heritage Dictionary or your preferred dictionary)}.

When writing documentation for our project, align with the default guide's voice and tone.

Glossary of preferred terms

{(Calling out how to write your project name first is optional. You can choose to include your project name in the word list instead.)}

This {(Your Project Name)} is represented as {(example)}. It is {(always/never)} capitalized.

The table provides guidelines about the terms you should and should not use for consistency, listed in alphabetical order:

Topic types and templates

This project recommends using the following templates from the Good Docs project:

• API Overview

• API Quickstart

• API Reference

• Discussion Article

• How To Guide

• Logging Article

• Reference Article

• Tutorial

General writing tips

{(This section is optional.)}

For some general tips about improving writing see:

• Write the Docs - Style Guides

• 18F Content Guide

Accessible writing

Documentation should be written in a way that supports people with disabilities and users with various input methods and devices. Improving accessibility also helps make documentation clearer and more useful for everyone.

For resources on making your writing more accessible, see:

• Writing accessible documentation - Google developer documentation style guide

• Accessibility guidelines and requirements - Microsoft Writing Style Guide

• Writing for Accessibility - Mailchimp Content Style Guide

Inclusive and bias-free writing

When contributing to this project, you should strive to write documentation with inclusivity and diversity in mind. Inclusive language recognizes diversity and strives to communicate respectfully to all people. This kind of language is sensitive to differences and seeks to promote equal opportunities.

For resources on making your writing more inclusive, see:

• Inclusive documentation - Google developer documentation style guide

• The Conscious Style Guide - a collection of resources

• Bias-free communication - Microsoft Writing Style Guide

• Guidelines for Inclusive Language - Linguistic Society of America

Using linters

{(This section is optional.)}

This project uses the {(your preferred linter.)}

{(Provide instructions or policies related to the linter here.)}

How the style guide is updated

{(Indicate here how frequently your style guide is reviewed, who owns the style guide, and how contributors can provide feedback on your style guide.)}

Revision history

{(This section is optional or can be combined with the next section if needed.)}

The following table describes the history of all decisions and revisions made to this style guide over time. This guide uses the Major.Minor.Patch semantic versioning convention.

Decision log

{(This section is optional or can be combined with the previous section if needed.)}

The following table describes the history of all decisions made to this style guide over time:

tip

Explore other templates from The Good Docs Project. Use our feedback form to give feedback on this template.