From 92d8ea4eaf51f88d53e96cf6d4fa7d5eb2a8397d Mon Sep 17 00:00:00 2001 From: Kim Pohas Date: Sat, 31 May 2025 00:02:57 -0400 Subject: [PATCH 1/2] Clarify screenshot image guidance in Style Guide --- docs/contributing/style-guide.md | 39 ++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/docs/contributing/style-guide.md b/docs/contributing/style-guide.md index 1577517faa..0ad6cb3938 100644 --- a/docs/contributing/style-guide.md +++ b/docs/contributing/style-guide.md @@ -735,13 +735,9 @@ You can use a link to a file embedding the entire file, or embed a range of code -### Image sizes +### Logos -When sizing images, use your discretion. - -#### Logos - -For square logos, set the width to about 45-55px. +When sizing images, use your discretion. For square logos, set the width to about 45-55px. | ✅ **Do** | ❌ **Don't** | |:---------------|:-------------------| @@ -749,16 +745,32 @@ For square logos, set the width to about 45-55px. For wide logos (like [in this doc](/docs/integrations/microsoft-azure/iis-7/)), set the width to about 90-120px. -#### Screenshots +### Screenshots + +Use screenshots only when they clarify complex instructions. Our UI changes often, so minimizing screenshots reduces maintenance overhead. + +* Prefer clear, concise text instructions over images when possible. +* Only include screenshots if they significantly aid user understanding. +* Avoid screenshots for simple UI interactions. +* When updating docs, evaluate whether screenshots are outdated or redundant. +* If you come across unnecessary screenshots, use your judgment to delete or replace them. -Ensure that screenshots are large enough so that the content is legible, but not comically oversized. Use your discretion. +Make sure screenshots are large enough to be legible, but never wider than 800px. Avoid oversized images. + +By default, images that you insert into a page are set to be responsive - resized for the type of device the reader is using. + +Use the following syntax to add screenshots: + +```md +.png')} alt="Descriptive alt text" style={{border: '1px solid gray'}} width="500" /> +``` + +Add appropriate `alt` text for accessibility. See [Add an image](#add-an-image) for more. | ✅ **Do** | ❌ **Don't** | |:---------------|:-------------------| | alt-text | alt-text | -Screenshots should never be wider than 600px. - ### Images in lists When adding an image to a bulleted or sequential list, include the image snippet in-line with the list item, with a `
` element in between, like this: @@ -785,13 +797,6 @@ When adding an image to a bulleted or sequential list, include the image snippet -### Screenshots - -Capture screenshots using SnagIt in .png format. Use SnagIt's border effect to apply a gray (RGB 212, 212, 212) four-point border. - -By default, images that you insert into a page are set to be responsive - resized for the type of device the reader is using. - - ### Masking sensitive information We mask sensitive information like usernames, email addresses, and IP addresses. In Snagit or a similar program, use the shape tool to mask the text using solid gray, (RGB 212, 212, 212). From 16b38f38f5e27a1e0c7191cb8222817c299441b2 Mon Sep 17 00:00:00 2001 From: "Kim (Sumo Logic)" <56411016+kimsauce@users.noreply.github.com> Date: Mon, 2 Jun 2025 12:48:12 -0700 Subject: [PATCH 2/2] Update docs/contributing/style-guide.md Co-authored-by: John Pipkin (Sumo Logic) --- docs/contributing/style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/style-guide.md b/docs/contributing/style-guide.md index 0ad6cb3938..ea343e3780 100644 --- a/docs/contributing/style-guide.md +++ b/docs/contributing/style-guide.md @@ -757,7 +757,7 @@ Use screenshots only when they clarify complex instructions. Our UI changes ofte Make sure screenshots are large enough to be legible, but never wider than 800px. Avoid oversized images. -By default, images that you insert into a page are set to be responsive - resized for the type of device the reader is using. +By default, images that you insert into a page are set to be responsive-resized for the type of device the reader is using. Use the following syntax to add screenshots: