Screenshots and images

Images help to illustrate confusing UI paths, complex concepts like config file overrides, or sometimes just to add visual interest. Whenever possible, send the Docs team a permalink rather than an image.

The goal of this document it to give you some tips about creating images, but if you need help embedding them on our site, see Embed images.

Guidelines for image types

Review the Tech Docs team's five questions to decide how to write excellent docs and to convey information visually. Depending on the type of image, follow these guidelines.

Guidelines for explaining images

Supporting text can provide helpful context and explanation, especially for complicated screenshots and other images that may be tricky to understand on their own. While you should always include alt text for accessibility, the other types of supporting text are optional. Read on for guidelines and suggestions for when to use them.

• Alt text (required)
• Caption
• Surrounding text
• Annotations within the image

Alt text (Required)

Always include alt text in your image tags so visually impaired readers can use their screen readers to get useful information out of the images. This only applies to images that contain content or commands (for example, buttons).

When using alt text:

• Use concise image descriptions.
• Don't repeat surrounding text—screen readers already read that.
• Aim for clarity. Complete sentences aren't required.
• Identify the type of image in some way:
  • <img alt="Diagram showing the flow of data from client to server.">
  • <img alt="Screen capture showing how to select a server.">
  • <img alt="Photo of garden hose that serves as a metaphor for electrical amperage.">

Caption

Captions appear below images and give supporting context to readers.

Keep the following in mind:

• Keep captions short and don’t insert procedures.
• Only insert navigation paths in captions if navigation is a key part of the message.
• Insert complementary information not identical to surrounding text.
• Make captions that are easy to skim.
• Encourage readers to look at surrounding text.
• Don't put required information in captions that isn't available elsewhere.
• Captions aren't necessary in procedure screenshots because the procedure text should make things clear.
• Use "Figure X" to refer to images elsewhere. Include a link to the image.

Surrounding text

If you're not using captions or annotations, be sure to add text before or after the image to give helpful context.

If you're relying on surrounding text to explain your image:

• Use intuitive images.
• Keep the surrounding text concise so it's easier to make sense of the image.

Image annotations

Image annotations are text and shapes in screen captures or diagrams that help to explain the image. If an image has annotations that explain what readers need to know, captions may be redundant.

When using annotations:

• Be concise.
• Make sure annotations are easy to distinguish from UI text. For example, you may need to offset your boxes so they don't look like UI elements.
• Annotations aren't translated, so use them sparingly.
• Use our New Relic SnagIt theme (link only available to New Relic employees) to keep your annotations consistent. To import the New Relic theme:
  1. Open SnagIt.
  2. In the Quick Styles pane, select the Theme gear icon.
  3. Select Import.