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

Style guide updates: headers and linking guidance (#29643)

Browse Source 
* Fix spacing errors

* Add guidance on linking to specific sections of articles

* Add link to Titles section of content model
This commit is contained in:
Ethan Palm
2022-08-08 09:18:49 -07:00
committed by GitHub
parent ef277d6640
commit f936c2d8ea
1 changed files with 22 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -61,7 +61,6 @@ Within code blocks:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
``` ```
### Commands ### Commands
Use inline code blocks to refer to short command names. Use inline code blocks to refer to short command names.
@@ -122,6 +121,8 @@ Workflow runs are delayed when too many workflows run at once. Since many users
Use H2 for headers, and H3 for subheaders. When referring to headers, surround the header name with quotation marks. Use H2 for headers, and H3 for subheaders. When referring to headers, surround the header name with quotation marks.
- **Use:** Under “User licenses”, view your total licenses. - **Use:** Under “User licenses”, view your total licenses.
Our guidelines for writing titles also apply to writing headers. For more information, see the [content model](/contributing/content-model.md#titles).
To orient readers and help them understand if the section is relevant to them, include introductory content after a header - don’t locate a subheader directly following a header. To orient readers and help them understand if the section is relevant to them, include introductory content after a header - don’t locate a subheader directly following a header.
## Images ## Images
@@ -233,6 +234,7 @@ For plain text, use linebreaks to separate paragraphs in the source (two consecu
Introduce links consistently using a standard format that clearly indicates where we’re linking. Introduce links consistently using a standard format that clearly indicates where we’re linking.
For links to other articles in the GitHub docs: `For more information, see "[Page or article title]()."` For links to other articles in the GitHub docs: `For more information, see "[Page or article title]()."`
For links to another section in the same article: `For more information, see "[Header text]()."` For links to another section in the same article: `For more information, see "[Header text]()."`
For links to specific sections in other articles in the GitHub docs: `For more information, see "[Article title]()."`
For links to external documentation: `For more information, see [Page or article title]() in the X documentation.` For links to external documentation: `For more information, see [Page or article title]() in the X documentation.`
Do not include quotation marks within a hyperlink. Do not include quotation marks within a hyperlink.
@@ -262,6 +264,16 @@ To link to the same article in a different version, use this format:
To link to a specific version, you must include the version in the path (e.g., `/enterprise-cloud@latest/admin/overview/about-enterprise-accounts`). To link to a specific version, you must include the version in the path (e.g., `/enterprise-cloud@latest/admin/overview/about-enterprise-accounts`).
### Links to specific sections of articles
When we link to specific sections of articles, we want to make sure the link is descriptive enough so that someone knows they are in the correct spot after following a link.
To link to a specific header in the same article, use this format:
> For more information, see "[HEADER TITLE](#HEADER-TITLE)."
To link to a specific header in a different article, use this format:
> For more information, see "[ARTICLE TITLE](path-to-article#HEADER-TITLE)."
### Links to learning paths ### Links to learning paths
Use this format to link to a learning path. Use this format to link to a learning path.
@@ -668,7 +680,7 @@ When specifying the access required to take an action, refer only to the role at
- **Use:** `People with write access to a repository can do X to the repository.` - **Use:** `People with write access to a repository can do X to the repository.`
- **Avoid:** `Organization owners and people with write access can do X to the repository.` - **Avoid:** `Organization owners and people with write access can do X to the repository.`
For more information about word choice for permissions statments, see "[Permissions statements](/contributing/content-model.md#permissions-statements)" in the content model. For more information about word choice for permissions statements, see "[Permissions statements](/contributing/content-model.md#permissions-statements)" in the content model.
### Prepositions ### Prepositions