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.

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

Docs: Add examples to screenshot guidelines #1050

Merged
merged 10 commits into from
Feb 19, 2025
2 changes: 1 addition & 1 deletion docs/sources/contribute/release-notes/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ If you add an entry to the CMS after the relevant versioned What's new has alrea
| SELF-MANAGED AVAILABILITY | Select the stage of the feature's self-managed release. | If the feature isn't available in the self-managed product, select **None**. |
| SELF-MANAGED EDITIONS | Select the on-premises offerings where this feature is available. | If the feature isn't available in the self-managed product, select **None**. |
| SELF-MANAGED VERSION | Select the version of self-managed product that will include the feature. | <p>If the feature isn't available in the self-managed product, select **None**.</p><p>If the version isn't available, select **No suitable option** and reach out in the **#docs** Slack channel so that a maintainer can add a new option. |
| BODY | Include an overview of the feature and the problem it solves. | If you want to view some best practices around what to write here, refer to [Guidelines for What's new content](#guidelines-for-whats-new-content).</p><p>Add any images and a link to your public YouTube video here.</p><p>If you need more information on adding an image, refer to [Image, diagram, and screenshot guidelines](https://grafana.com/docs/writers-toolkit/write/image-guidelines/).</p><p>If you need to mention a feature flag, use this format: To try out Trace to profiles, enable the `traceToProfile` [feature toggle](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/feature-toggles/).</p> |
| BODY | Include an overview of the feature and the problem it solves. | If you want to view some best practices around what to write here, refer to [Guidelines for What's new content](#guidelines-for-whats-new-content).</p><p>Add any [screenshots](https://grafana.com/docs/writers-toolkit/write/image-guidelines/#screenshot-guidelines) or [screen recordings](https://grafana.com/docs/writers-toolkit/write/image-guidelines/#screen-recordings) here. For general information on adding media, refer to [Image and diagram guidelines](https://grafana.com/docs/writers-toolkit/write/image-guidelines/#image-and-diagram-guidelines).</p><p>If you need to mention a feature flag, use this format: To try out Trace to profiles, enable the `traceToProfile` [feature toggle](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/feature-toggles/).</p> |
| DOCUMENTATION URL (OPTIONAL) | URL to the public documentation for this feature. | Use the Cloud docs URL here. Add the self-managed docs URL in the INTERNAL INFORMATION field, if applicable. |
| ENABLEMENT VIDEO (OPTIONAL) | Link to the video used for enablement. | <p>Enablement videos are perhaps the fastest, most engaging tool for employees and users to learn about your feature. Use them for maximum engagement.</p><p>Follow these instructions to create and upload a video: [Enablement video instructions](https://docs.google.com/document/d/1nCiG62FxJ9J_qLTnlzNopSsT-VEAlxCUCsrAEpWL68U/edit#heading=h.fierz9i4q8ft).</p><p>When you upload an enablement video, the Content team receives a notification, edits it for the public, and uploads it to YouTube to coincide with your feature's release. They need a few weeks' lead time for this. |
| INTERNAL INFORMATION (OPTIONAL) | Information for Grafana Labs employees only. | For example, ProductDNA, Slack channel, FAQ, training documentation, or videos.</p><p>Used for training and internal announcements.</p><p>This is only visible on the [internal What's new page](https://admin.grafana.com/whats-new/), not the [public What's New page](https://grafana.com/docs/grafana-cloud/whats-new/).</p> |
Expand Down
1 change: 1 addition & 0 deletions docs/sources/whats-new.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ This page provides a summary of notable changes to Writers' Toolkit guidance.
| Fixed the path to the section template file. | https://raw.githubusercontent.com/grafana/writers-toolkit/refs/heads/main/docs/static/templates/section-template.md |
| Added `topic/<TYPE>` Make targets to create a topic from its template | [Topic types](/docs/writers-toolkit/structure/topic-types/) |
| Added `video-embed` to Shortcodes page. | [Shortcodes](/docs/writers-toolkit/write/shortcodes/#video-embed) |
| Added examples to screenshot guidelines | [Screenshot guidelines](/docs/writers-toolkit/write/image-guidelines/#screenshot-examples) |

## January 2025

Expand Down
18 changes: 18 additions & 0 deletions docs/sources/write/image-guidelines/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,24 @@ Consult the following guidelines when you create screenshots:
- **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.

Refer to the next section for examples of good screenshots.

#### Screenshot examples

Good example of size at 545 pixels wide:
![Good size example](/media/docs/grafana/panels-visualizations/screenshot-stat-single-value-v11.3.png)
Copy link
Contributor

Choose a reason for hiding this comment

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

Note this image looks a little blurry on high dpi screens.

In this case I would suggest a file that is 2x resolution, or 1090px wide, and then limited to 545px wide with the figure shortcode's max-width argument.

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'd like to pick your brain a bit about this offline.

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 image and booked a meeting with you to go over my confusion around this stuff!


Good examples of scope on smaller scale:
{{< figure src="/media/docs/grafana/dashboards/screenshot-panel-links-v11.3.png" max-width="600px" alt="Good scope example 1" >}}
{{< figure src="/media/docs/grafana-cloud/k8s/side-menu.png" max-width="350px" alt="Good scope example 2" >}}

Good examples of scope on a larger scale that allows the user to see all they need to without enlarging or opening the image in a separate tab:
![Good example of a full page](/media/docs/alerting/alert-rule-evaluation.png)
![Good scale example](/media/docs/grafana/panels-visualizations/screenshot-traces-visualization-11.5.png)

Good example of annotation use:
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-regexp-format-v11.3.png" max-width="600px" alt="Good PII and annotation example" >}}

## Video guidelines

Use the following guidelines when you add video content:
Expand Down