jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 18:10:59 -05:00
Code Issues Projects Releases Wiki Activity

Clarify guidance on introducing lists with "the following" and "these" (#45186)

Browse Source
This commit is contained in:
Sam Browning
2023-10-27 13:35:40 -04:00
committed by GitHub
parent 29360c7583
commit b45145e26b
3 changed files with 28 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
content/contributing/style-guide-and-content-model/style-guide.md
View File

@@ -534,7 +534,15 @@ Formatting unordered lists:
- If the order of items in the list is not important, alphabetize the list items. - If the order of items in the list is not important, alphabetize the list items.
- If the order is important, then order the list by the importance to the reader (for example, moving from broadest audience and applicability to a more specialized audience). - If the order is important, then order the list by the importance to the reader (for example, moving from broadest audience and applicability to a more specialized audience).
When introducing a list, avoid phrasing like “the following” or “these”, terms which are difficult to localize. Instead, be descriptive, yet general enough to allow a list to scale or change without having to update the description. When introducing a list, avoid short, nonspecific sentences using terms like “the following” or “these”, which are difficult to localize without context. Instead, create a descriptive sentence that clearly conveys the subject of the list, yet allows the list to scale or change without having to update the description.
**Use:**
- For an introduction to {% data variables.product.prodname_dotcom %}, see the following articles:
- SMS authentication is supported in these countries:
**Avoid:**
- There are several articles that provide an introduction to {% data variables.product.prodname_dotcom %}. See the following:
- SMS authentication is supported in 50 countries. These include:
## Placeholders ## Placeholders

2
contributing/content-model.md
View File

@@ -1,6 +1,6 @@
# Content model for GitHub Docs # Content model for GitHub Docs
**Note:** This version of the content model is no longer maintained and will be deprecated. See the [style guide](https://docs.github.com/en/contributing/writing-for-github-docs/style-guide) on docs.github.com for the most up to date version. Open any pull requests against the `contributing/writing-for-github-docs/style-guide.md` file. **Note:** This version of the content model is no longer maintained and will be deprecated. See the [content model](https://docs.github.com/contributing/style-guide-and-content-model/content-model) on docs.github.com for the most up-to-date version. Open any pull requests against the `contributing/style-guide-and-content-model/content-model.md` file.
_Full TOC :arrow_upper_left:_ _Full TOC :arrow_upper_left:_

2
contributing/content-style-guide.md
View File

@@ -1,6 +1,6 @@
# Content style guide for GitHub Docs <!-- omit in toc --> # Content style guide for GitHub Docs <!-- omit in toc -->
**Note:** This version of the style guide is no longer maintained and will be deprecated. See the [content model](https://docs.github.com/en/contributing/writing-for-github-docs/content-model) on docs.github.com for the most up to date version. Open any pull requests against the `contributing/writing-for-github-docs/content-model.md` file. **Note:** This version of the style guide is no longer maintained and will be deprecated. See the [style guide](https://docs.github.com/contributing/style-guide-and-content-model/style-guide) on docs.github.com for the most up-to-date version. Open any pull requests against the `contributing/style-guide-and-content-model/style-guide.md` file.
Welcome to the content style guide for [GitHub Docs](https://docs.github.com/). Welcome to the content style guide for [GitHub Docs](https://docs.github.com/).