From 0d34486ed0e733503ecbfa23f491c912ea75c0f4 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 2 Jan 2024 08:44:14 -0800 Subject: [PATCH] Content strategy bug fix hour 2023-12-20 (#48211) --- .../style-guide-and-content-model/style-guide.md | 8 +++++--- .../using-videos-in-github-docs.md | 11 ++++++----- 2 files changed, 11 insertions(+), 8 deletions(-) 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 1d7f55e92eb9..1e4738d210bd 100644 --- a/content/contributing/style-guide-and-content-model/style-guide.md +++ b/content/contributing/style-guide-and-content-model/style-guide.md @@ -620,7 +620,7 @@ Examples: ## Product names -Use full product names. Do not abbreviate or shorten product names unless directly reproducing content from the product (e.g. UI copy or API responses). +Use full product names. Do not abbreviate or shorten product names unless directly reproducing content from the product (e.g. UI copy or API responses). Product names are never possessive. Use product name variables to render product names - do not write product names in plain text. This makes product name changes easier to implement across the site and avoids typos in our product names. For more information about product name variables, see “[Reusables and variables](#reusables-and-variables)” in this document and the data directory of the github/docs repository. @@ -628,15 +628,17 @@ Product names are always singular. - **Use:** {% data variables.product.prodname_actions %} helps you automate your software development workflows. - **Avoid:** {% data variables.product.prodname_actions %} help you automate your software development workflows. -Take care to distinguish between product names and product elements. +Take care to distinguish between product names and product features. Product features are always lowercase. -| Product | Element | +| Product | Feature | | --- | --- | | {% data variables.product.prodname_actions %} | an action | | {% data variables.product.prodname_github_codespaces %} | a codespace | | {% data variables.product.prodname_registry %} | a package | | {% data variables.product.prodname_pages %} | a GitHub Pages site | +Do not capitalize commonly used features like pull requests, topics, or issues. + ## Product-specific conventions This section describes additional conventions that are specific to GitHub products. diff --git a/content/contributing/writing-for-github-docs/using-videos-in-github-docs.md b/content/contributing/writing-for-github-docs/using-videos-in-github-docs.md index b1bb665037b6..8adf3bb048e6 100644 --- a/content/contributing/writing-for-github-docs/using-videos-in-github-docs.md +++ b/content/contributing/writing-for-github-docs/using-videos-in-github-docs.md @@ -120,11 +120,12 @@ Creating transcripts is part of the process of producing videos that can be acce You can use captions as the foundation for a transcript. Edit the captions to remove any timestamps and include the relevant information detailed below. A descriptive transcript includes a text version of both audio and visual information needed to understand the content of a video. -- If a video has multiple speakers, identify the speakers in the transcript -- Format the transcript in logical paragraphs, lists, and sections. If it helps people understand the content, you may add headers to sections. Consider how someone would get information from the transcript if they are not also viewing the video -- Add any onscreen text, relevant visual elements, or non-speech sounds that are not included in the captions. Place these descriptions after the spoken text that accompanies them in the video. Format visual information in brackets. For example, `[Background music plays. The narrator clicks the Code button and then the "+ New codespace" button.]` -- Add a `product_video` property to the transcript article's YAML frontmatter. The value of the `product_video` property is the YouTube URL of the video. The video's YouTube URL will display as an external link in the transcript article -- At the end of the transcript, link to the landing page for the product the video is about using the pattern `For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page).` +- If a video has multiple speakers, identify the speakers in the transcript. +- If a speaker's gender is known, you can use their preferred pronouns when describing their actions. For example, `She points to the computer screen.` If the speaker's gender is unknown or irrelevant to the visual being described, you can use the singular they pronoun. +- Format the transcript in logical paragraphs, lists, and sections. If it helps people understand the content, you may add headers to sections. Consider how someone would get information from the transcript if they are not also viewing the video. +- Add any onscreen text, relevant visual elements, or non-speech sounds that are not included in the captions. Place these descriptions after the spoken text that accompanies them in the video. Format visual information in brackets. For example, `[Background music plays. The narrator clicks the Code button and then the "+ New codespace" button.]`. +- Add a `product_video` property to the transcript article's YAML frontmatter. The value of the `product_video` property is the YouTube URL of the video. The video's YouTube URL will display as an external link in the transcript article. +- At the end of the transcript, write `End of transcript.` and link to the landing page for the product the video is about using the pattern `For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page).`. See "[Text Transcript with Description of Visuals](https://www.w3.org/WAI/perspective-videos/captions/#transcript)" in the W3C docs for more examples of audio and visual transcriptions.