Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] Add information about alt text #349

Merged
merged 5 commits into from
Oct 18, 2023
Merged

[WIP] Add information about alt text #349

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3527f85
Add information about alt text
heitortsergent Oct 16, 2023
4056905
Add links to alt text section
heitortsergent Oct 16, 2023
9d391a4
Apply suggestions from code review
heitortsergent Oct 18, 2023
6adaea1
Add alt text example when using the figure shortcode
heitortsergent Oct 18, 2023
5aae728
Merge branch 'main' into alt-text
heitortsergent Oct 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions docs/sources/write/image-guidelines/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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](#alt-text) for every image. Figure captions are optional.

### Diagram assets

Expand Down Expand Up @@ -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](#alt-text) for every image.

## Media asset file naming conventions

Expand Down Expand Up @@ -272,6 +274,35 @@ 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 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:

```markdown
![Alt text](/media/<path-to-image/image-file.png>)
```

Copy link
Contributor

@imatwawana imatwawana Oct 17, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm thinking we should add an example using a figure shortcode here as well.

Speaking of the shortcode, the alt parameter is indicated as not required and I'm sure it isn't for the shortcode to work; should we change that or add a note there to clarify what's meant by required in that context? cc @jdbaldry

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like to make it required but it will break the website build if I do since so many invocations do not have that value set.

In my PR, I first emit a log warning which we can use to identify all the misuse. Once that's cleaned up, we can make it required.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated the PR to include an example with the figure shortcode as well. :)

Or, if you're using the `figure` [shortcode]({{< relref "../shortcodes#figure" >}}), you can use the `alt` parameter:

```markdown
{{</* figure alt="Alt text" src="/media/<path-to-image/image-file.png>" */>}}
```

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:

> "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:
Expand Down
Loading