diff --git a/style-guide/about-style-guide.md b/style-guide/about-style-guide.md index 19f5f7e4..13fabeba 100644 --- a/style-guide/about-style-guide.md +++ b/style-guide/about-style-guide.md @@ -68,7 +68,7 @@ you intend to use this style guide in your project. Feel free to adapt this content. If desired, you can briefly elaborate on the goals or mission of your project’s documentation. -### About the "Our Preferred Style Guide" section +### About the "Our preferred style guide" section Maintenance of a style guide is a lot of work. Try to do as little of it as possible by deferring to a more comprehensive default guide, such as the Google @@ -80,7 +80,7 @@ from your default guide. Also, if your project already has existing brand guidelines, you can link to them or include them here. -## About the "Glossary of Preferred Terms" section +## About the "Glossary of preferred terms" section Every project has its own unique terms and buzzwords and this glossary can help you record your project’s preferred terms. This word list provides a list of @@ -94,29 +94,29 @@ or which conflict with your default style guide. For example, the Google Developer's Guide uses "open source" but our project prefers "open-source" when used as a modifier, as in "open-source software." -## About the "Topic Types and Templates" section +## About the "Topic types and templates" section Depending on the type of project you’re creating, some of the Good Docs templates will be more relevant than others. In this section, you can link to the templates you have adopted for your project. You can also explain when contributors should use these templates. -## About the "General Writing Tips" section +## About the "General writing tips" section This section is optional. You can link to your favorite general writing tips or add some of your own general guidelines. -## About the "Accessible Writing" section +## About the "Accessible writing" section In this section, you can link to your preferred style guides about accessible writing or add some of your own general guidelines. -## About the "Inclusive and Bias-Free Writing" section +## About the "Inclusive and bias-free writing" section In this section, you can link to your favorite resources about inclusive and bias-free writing or add some of your own general guidelines. -## About the "Using Linters" section +## About the "Using linters" section This section is optional. [Linters](https://www.writethedocs.org/guide/tools/testing/#style-guide-checking-and-linting) are tools that analyze text content to flag common mistakes such as stylistic @@ -135,12 +135,10 @@ documentation with less cognitive overhead. For resources and examples of linters, see: - [The `linter-google-styleguide` package for the Atom text editor](https://atom.io/packages/linter-google-styleguide) -- A tool like [Vale](https://www.writethedocs.org/guide/tools/testing/#vale) - for a more automated approach, including styles such as the - [Microsoft Writing Style Guide](https://github.com/errata-ai/styles) +- A tool like [Vale](https://www.writethedocs.org/guide/tools/testing/#vale), + which can automate [several popular styles](https://github.com/errata-ai/styles) - -## About the "How the Style Guide is Updated" section +## About the "How the style guide is updated" section Indicate here how frequently your style guide is reviewed, who owns the style guide, and how contributors can provide feedback on your style guide. For @@ -150,7 +148,7 @@ reviewed in project meetings. If this section is small enough, you can combine it with the following sections. -## About the "Revision History" section +## About the "Revision history" section This section is optional. You can use this section to provide a changelog or decision log of changes to your project’s style guide. You can also link out to @@ -158,8 +156,7 @@ other project documents that contain your decision log. You could also use this section to provide guidelines about how to request changes to the style guide and outline how often decisions can be revisited (such as after a year). - -## About the "Decision Log" section +## About the "Decision log" section This section is optional. Various project managers, sponsors, and teams make a lot of decisions while working on a project long-term. A decision log can track diff --git a/style-guide/template-style-guide.md b/style-guide/template-style-guide.md index 6a710af8..99a3b0f5 100644 --- a/style-guide/template-style-guide.md +++ b/style-guide/template-style-guide.md @@ -11,10 +11,10 @@ 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. -## Our Preferred Style Guide +## Our preferred style guide We have adopted the -[your preferred style guide, such as the Google Developer's Style Guide](https://developers.google.com/style) +[your preferred style guide, such as the Google developer's style guide](https://developers.google.com/style) for {Your Project} documentation. For a quick summary, see the [Google style guide highlights](https://developers.google.com/style/highlights). The rest of this document describes our project-specific customizations to @@ -28,7 +28,7 @@ dictionary}. When writing documentation for our project, align with the default guide’s voice and tone. -## Glossary of Preferred Terms +## Glossary of preferred terms @@ -41,10 +41,10 @@ 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](#accessible-writing +people with disabilities | | Use inclusive and bias-free language. See [Accessible Writing](#accessible-writing) that is | i.e. | Avoid non-English words -## Topic Types and Templates +## Topic types and templates This project recommends using the following templates from the [Good Docs project](https://github.com/thegooddocsproject/templates): @@ -58,7 +58,7 @@ This project recommends using the following templates from the - Reference Article - Tutorial -## General Writing Tips +## General writing tips @@ -67,7 +67,7 @@ For some general tips about improving writing see: - [Write the Docs - Style Guides](https://www.writethedocs.org/guide/writing/style-guides/#writing-style) - [18F Content Guide](https://content-guide.18f.gov/) -## Accessible Writing +## 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 @@ -79,7 +79,7 @@ For resources on making your writing more accessible, see: - [Accessibility guidelines and requirements - Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/accessibility/accessibility-guidelines-requirements) - [Writing for Accessibility - Mailchimp Content Style Guide](https://styleguide.mailchimp.com/writing-for-accessibility/) -## Inclusive and Bias-Free Writing +## 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 @@ -88,12 +88,12 @@ sensitive to differences and seeks to promote equal opportunities. For resources on making your writing more inclusive, see: -- [Inclusive documentation - Google Developer’s Style Guide](https://developers.google.com/style/inclusive-documentation) +- [Inclusive documentation - Google developer’s style guide](https://developers.google.com/style/inclusive-documentation) - [The Conscious Style Guide - a collection of resources](https://consciousstyleguide.com/) -- [Bias-free communication - Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/bias-free-communication) +- [Bias-free communication - Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/bias-free-communication) - [Guidelines for Inclusive Language - Linguistic Society of America](https://www.linguisticsociety.org/resource/guidelines-inclusive-language) -## Using Linters +## Using linters @@ -106,7 +106,7 @@ This project uses the {your preferred linter.} -## Revision History +## Revision history @@ -121,12 +121,11 @@ Edition | Date | Lead Author(s) | Link to Repository Commit/Tag {0.1} | {1/1/11} | {Your name here} | First draft of Style Guide -## Decision Log +## Decision log The following table describes the history of all decisions made to this style guide over time. - Ref | Date | Description | Agreed to by --- | ---- | ----------- | ------------ 1 | {1/1/11} | {Explain the decision that was made here} | {Name or role}