From f57afe390e7d9709bfd7cb975e8629bab54a0bb8 Mon Sep 17 00:00:00 2001 From: Thom Wong <101249231+supergranular@users.noreply.github.com> Date: Tue, 31 Jan 2023 09:45:51 +0100 Subject: [PATCH] Accessibility changes around header and titles. (#34222) Co-authored-by: Laura Coursen Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> --- contributing/content-model.md | 18 +++++++++++------- contributing/content-style-guide.md | 8 ++++---- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/contributing/content-model.md b/contributing/content-model.md index e385870b61d6..cdbe7a2b6510 100644 --- a/contributing/content-model.md +++ b/contributing/content-model.md @@ -109,15 +109,23 @@ We organize content predictably within categories, map topics, and articles, fro ### Titles -Titles are challenging! Use these general guidelines to help create clear, helpful, descriptive titles, and see below for specific guidelines for each content type. +Titles fully describe what a page is about, and what a user will know by reading it. + +Titles are challenging! Use these general guidelines to help create clear, helpful, and descriptive titles. See below for specific guidelines for each content type. #### Titles for all content types -- Titles are clear, descriptive, and specific, but not wordy +- 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) < 27 characters + - Map topic titles: 63 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) < 30 characters + - Article titles: 80 characters, 60 if possible, and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) < 31 characters, ideally 20-25 characters - Titles are consistent across a content type - See specific guidelines for each content type - - Titles aren’t overly repetitive––vary the verbs used for procedure or map topic titles when possible + - Titles aren’t repetitive––vary the verbs used for procedure or map topic titles when possible - Titles are general enough to scale with product changes, reflect all of the content within the article, or include content on multiple products - Use: "GitHub's billing plans" - Avoid: "Billing plans for user and organization accounts" @@ -131,10 +139,6 @@ Titles are challenging! Use these general guidelines to help create clear, helpf - 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 -- 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) < 27 characters - - Map topic titles: 63 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) < 30 characters - - Article titles: 80 characters, 60 if possible, and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) < 31 characters, ideally 20-25 characters ### Topics diff --git a/contributing/content-style-guide.md b/contributing/content-style-guide.md index 2c79f4064b18..2b4447b551b5 100644 --- a/contributing/content-style-guide.md +++ b/contributing/content-style-guide.md @@ -127,12 +127,12 @@ Workflow runs are delayed when too many workflows run at once. Since many users ## Headers -Use H2 for headers, and H3 for subheaders. Articles must start with an H2 level header and cannot skip header levels. There must be content between a header and subheader. When referring to headers, surround the header name with quotation marks. -- **Use:** Under “User licenses”, view your total licenses. +Headers must adequately describe the content under it. Follow the same guidelines we use for writing titles. Each header on a page must be unique. -Each header on a page must be unique. Our guidelines for writing titles also apply to writing headers. For more information, see the [content model](/contributing/content-model.md#titles). +Use H2 for headers, and H3 for subheaders. Articles 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. -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. +For more information, see the [content model](/contributing/content-model.md#titles). ## Images