Version number: 1.0 Last updated: August 30, 2022
Welcome to the Templates Style Guide! This style guide is intended for use by contributors of the Templates and Community Docs working groups. It provides general guidance to anyone who contributes to creating templates, accompanying guides, and deep-dive documents for The Good Docs Project (TGDP).
This style guide is intended for use by any contributor who is creating templates, accompanying guides, and deep-dive documents. This style guide can help contributors produce consistent documentation.
We have adopted the Google developer documentation style guide for creating templates, accompanying guides, and deep-dive documents. For a quick summary, see the Google style guide highlights.
The rest of this document describes our project-specific customizations to Google's style guide.
Our project uses standard American spelling and our preferred dictionary is the {American Heritage Dictionary.
When creating templates, guides, and deep-dive documents, align with the default guide's voice and tone.
{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 |
|
Use inclusive and bias-free language. See Accessible Writing |
| that is | i.e. | Avoid non-English words |
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
{This section is optional.}
For some general tips about improving writing see:
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
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
{This section is optional.}
This project uses the {your preferred linter.}
{Provide instructions or policies related to the linter here.}
{Indicate here how frequently your style guide is reviewed, who owns the style guide, and how contributors can provide feedback on your style guide.}
{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 |
{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} |