UX Writing Technical Specification API Docs Technical Documentation Knowledge Base Translation English Installation Guides Help Docs Troubleshooting Handbooks Support Docs Project Docs Portuguese Release Notes German SDK Product Discovery UX Design Spanish Copywriting Microcopy Educational Material Localization User Guides
{Your Project Name} style guide
{Version number and last updated date}
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:
| Preferred Term | Avoid These Terms | Explanation |
|---|---|---|
| for example | e.g. | Avoid non-English words |
| people with disabilities | <ul><li>the disabled</li><li>disabled people</li><li>people with handicaps</li><li>the handicapped</li></ul> | Use inclusive and bias-free language. See Accessible Writing |
| that is | i.e. | Avoid non-English words |
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:
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.
| Edition | Date | Lead Author(s) | Link to Repository Commit/Tag |
|---|---|---|---|
| {0.1} | {YYYY-MM-DD} | {Your name here} | First draft of Style Guide |
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:
| Ref | Date | Description | Agreed to by |
|---|---|---|---|
| 1 | {YYYY-MM-DD} | {Explain the decision that was made here} | {Name or role} |