diff --git a/content/contributing/style-guide-and-content-model/contents-of-a-github-docs-article.md b/content/contributing/style-guide-and-content-model/contents-of-a-github-docs-article.md index ff54f200607e..3846d70ff3af 100644 --- a/content/contributing/style-guide-and-content-model/contents-of-a-github-docs-article.md +++ b/content/contributing/style-guide-and-content-model/contents-of-a-github-docs-article.md @@ -22,29 +22,31 @@ Titles can be challenging. Use these general guidelines to help create clear, he ### Titles for all content types - Titles clearly describe what a page is about. They are descriptive and specific. - - Use: Browsing actions in the workflow editor - - Use: Example of configuring a codespace - - Avoid: Using the workflow editor sidebar - - Avoid: Example - - Titles have hard limits for length to keep them easy to understand (and easier to render on the site): - - Category titles: 67 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 26 characters - - Map topic titles: 63 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 29 characters - - Article titles: 80 characters, 60 if possible, and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 30 characters, ideally 20-25 characters -- Titles are consistent across a content type - - See specific guidelines for each content type -- Titles are general enough to scale with product changes, reflect all of the content within the article, or include content on multiple products + - Use: "Browsing actions in the workflow editor" + - Use: "Example of configuring a codespace" + - Avoid: "Using the workflow editor sidebar" + - Avoid: "Example" +- Titles have hard limits for length to keep them easy to understand (and easier to render on the site): + - Category titles: 67 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 26 characters + - Map topic titles: 63 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 29 characters + - Article titles: 80 characters, 60 if possible, and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 30 characters, ideally 20-25 characters +- Titles use sentence case. + - Use: "Changing a commit message" + - Avoid: "Changing A Commit Message" +- Titles are consistent across a content type. See specific guidelines for each content type. +- Titles are general enough to scale with product changes, reflect all of the content within the article, or include content on multiple products. - Use: "{% data variables.product.company_short %}'s billing plans" - Avoid: "Billing plans for user and organization accounts" -- Titles use consistent terminology - - Develop and follow patterns within a category or on similar subjects -- Titles use terminology from the product itself -- Write the title and the intro at the same time - - Use the intro to develop the ideas presented in the title - - See guidance on intros for more information +- Titles use consistent terminology. + - Develop and follow patterns within a category or on similar subjects. +- Titles use terminology from the product itself. +- Write the title and the intro at the same time. + - Use the intro to develop the ideas presented in the title. + - See guidance on [intros](#intro) for more information. - If it's hard to come up with a title, consider the content type. Sometimes trouble choosing a title indicates that another content type would fit better. -- Think about how the title will appear in search results for multiple products +- Think about how the title will appear in search results for multiple products. - What specific words do we need to include in the title or intro so that folks don’t mistake it for content about a different product? -- Think about how the title will look in production +- Think about how the title will look in production. ## Product callout diff --git a/content/contributing/style-guide-and-content-model/style-guide.md b/content/contributing/style-guide-and-content-model/style-guide.md index 8d29c9940d05..1dcb4f697106 100644 --- a/content/contributing/style-guide-and-content-model/style-guide.md +++ b/content/contributing/style-guide-and-content-model/style-guide.md @@ -212,7 +212,7 @@ Note that regardless of the identifier you use (letters, words), footnotes will ## Headers -Headers must adequately describe the content under them. Follow the same guidelines we use for writing titles. Each header on a page must be unique. +Headers must adequately describe the content under them. Follow the same guidelines we use for writing titles. Use sentence casing for headers. Each header on a page must be unique. Use H2 for headers, and H3 for subheaders. If the article has headers, the headers must start with an H2 level header and cannot skip header levels. There must be content between a header and subheader, such as an introduction. When referring to headers, surround the header name with quotation marks. - **Use:** Under "User licenses," view your total licenses.