From 3527f852ec60aa11f76b035039827f485da902b7 Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Mon, 16 Oct 2023 18:07:22 -0500 Subject: [PATCH 1/4] Add information about alt text --- docs/sources/write/image-guidelines/index.md | 25 ++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/sources/write/image-guidelines/index.md b/docs/sources/write/image-guidelines/index.md index 83ba9492b..25750d7e8 100644 --- a/docs/sources/write/image-guidelines/index.md +++ b/docs/sources/write/image-guidelines/index.md @@ -54,6 +54,7 @@ Use the following standards for images and diagrams: If it is, you must obtain permission and acknowledge credit. - **File name**: Use the naming convention documented in [Media asset file naming conventions](#media-asset-file-naming-conventions). - **Personal identifiable information (PII)**: Make sure to mask, modify, or remove any PII such as passwords, logins, account details, or other information that could compromise security. +- **Alt text and figure captions**: Make sure to include alt text for every image. Figure captions are optional. ### Diagram assets @@ -119,6 +120,7 @@ Consult the following guidelines when you create screenshots: - **Annotations**: To annotate a screenshot, use red (hexadecimal color **FF0000**) arrows and boxes. - **File name**: Use the naming convention documented in [Media asset file naming conventions](#media-asset-file-naming-conventions). - **Personal identifiable information (PII)**: Make sure to mask, modify, or remove any PII such as passwords, logins, account details, or other information that could compromise security. +- **Alt text**: Make sure to include alt text for every image. ## Media asset file naming conventions @@ -272,6 +274,29 @@ It is important that you generate a local build of your docs so that you can ver 1. Run `make docs` on your branch and verify that the image appears. 1. (Optional) Upload a new version and test again. +## Alt text + +Alt text is an HTML attribute that you can use to provide a concise description of an image. The text is used in situations where the image isn't visible, such as people using screen readers, or people who have a low-bandwidth internet connection. + +In Markdown, the alt text is the text in square brackets when declaring an image: + +```markdown +![Alt text](/media/) +``` + +Every image that you add to the Grafana documentation should have an alt text. + +A good guidance for writing good alt text from "[HTML: The Living Standard](https://html.spec.whatwg.org/dev/images.html#alt)" is: + +> "One way to think of alternative text is to think about how you would read the page containing the image to someone over the phone, without mentioning that there is an image present. Whatever you say instead of the image is typically a good start for writing the alternative text." + +For more information about how to write good alt text, refer to: + +- [Google developer documentation style guide](https://developers.google.com/style/images#alt-text) +- [HTML: The Living Standard](https://html.spec.whatwg.org/dev/images.html#alt) +- [gov.uk Design102 blog: What’s the alternative? How to write good alt text](https://design102.blog.gov.uk/2022/01/14/whats-the-alternative-how-to-write-good-alt-text/) +- [W3C Web Accessibility Initiative: An alt Decision Tree](https://www.w3.org/WAI/tutorials/images/decision-tree/) + ## Screen recordings The recommended format for screen recordings is **.mp4**. Do not use **.gif** or **.mov** formats. Screen recordings follow the same upload procedure and file naming convention as other media assets. Use the `video-embed` shortcode to embed the video on the page: From 40569059af610e24864688ae7d17fc3672522f9e Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Mon, 16 Oct 2023 18:08:28 -0500 Subject: [PATCH 2/4] Add links to alt text section --- docs/sources/write/image-guidelines/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/write/image-guidelines/index.md b/docs/sources/write/image-guidelines/index.md index 25750d7e8..1bda15f89 100644 --- a/docs/sources/write/image-guidelines/index.md +++ b/docs/sources/write/image-guidelines/index.md @@ -54,7 +54,7 @@ Use the following standards for images and diagrams: If it is, you must obtain permission and acknowledge credit. - **File name**: Use the naming convention documented in [Media asset file naming conventions](#media-asset-file-naming-conventions). - **Personal identifiable information (PII)**: Make sure to mask, modify, or remove any PII such as passwords, logins, account details, or other information that could compromise security. -- **Alt text and figure captions**: Make sure to include alt text for every image. Figure captions are optional. +- **Alt text and figure captions**: Make sure to include [alt text](#alt-text) for every image. Figure captions are optional. ### Diagram assets @@ -120,7 +120,7 @@ Consult the following guidelines when you create screenshots: - **Annotations**: To annotate a screenshot, use red (hexadecimal color **FF0000**) arrows and boxes. - **File name**: Use the naming convention documented in [Media asset file naming conventions](#media-asset-file-naming-conventions). - **Personal identifiable information (PII)**: Make sure to mask, modify, or remove any PII such as passwords, logins, account details, or other information that could compromise security. -- **Alt text**: Make sure to include alt text for every image. +- **Alt text**: Make sure to include [alt text](#alt-text) for every image. ## Media asset file naming conventions From 9d391a4423dacad81389828f4b0dcc085ff08174 Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Wed, 18 Oct 2023 14:01:22 -0500 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> --- docs/sources/write/image-guidelines/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/write/image-guidelines/index.md b/docs/sources/write/image-guidelines/index.md index 1bda15f89..d864c0c51 100644 --- a/docs/sources/write/image-guidelines/index.md +++ b/docs/sources/write/image-guidelines/index.md @@ -276,7 +276,7 @@ It is important that you generate a local build of your docs so that you can ver ## Alt text -Alt text is an HTML attribute that you can use to provide a concise description of an image. The text is used in situations where the image isn't visible, such as people using screen readers, or people who have a low-bandwidth internet connection. +Alt text is an HTML attribute that you can use to provide a concise description of an image. The text is used in situations where the image isn't visible, such as when people use screen readers or have a low-bandwidth internet connection. In Markdown, the alt text is the text in square brackets when declaring an image: @@ -286,7 +286,7 @@ In Markdown, the alt text is the text in square brackets when declaring an image Every image that you add to the Grafana documentation should have an alt text. -A good guidance for writing good alt text from "[HTML: The Living Standard](https://html.spec.whatwg.org/dev/images.html#alt)" is: +A good piece of guidance for writing good alt text from "[HTML: The Living Standard](https://html.spec.whatwg.org/dev/images.html#alt)" is: > "One way to think of alternative text is to think about how you would read the page containing the image to someone over the phone, without mentioning that there is an image present. Whatever you say instead of the image is typically a good start for writing the alternative text." From 6adaea1122c38958426a3c05acd519fe4455256d Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Wed, 18 Oct 2023 14:12:08 -0500 Subject: [PATCH 4/4] Add alt text example when using the figure shortcode --- docs/sources/write/image-guidelines/index.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/sources/write/image-guidelines/index.md b/docs/sources/write/image-guidelines/index.md index d864c0c51..c187b5f34 100644 --- a/docs/sources/write/image-guidelines/index.md +++ b/docs/sources/write/image-guidelines/index.md @@ -284,6 +284,12 @@ In Markdown, the alt text is the text in square brackets when declaring an image ![Alt text](/media/) ``` +Or, if you're using the `figure` [shortcode]({{< relref "../shortcodes#figure" >}}), you can use the `alt` parameter: + +```markdown +{{" */>}} +``` + Every image that you add to the Grafana documentation should have an alt text. A good piece of guidance for writing good alt text from "[HTML: The Living Standard](https://html.spec.whatwg.org/dev/images.html#alt)" is: