Images are a critical part of our docs. They show users what they'll get out of following a procedure. They can help orient users through a tricky UI path, illustrate complex concepts like config file overrides, or sometimes just add visual interest.
This doc describes best practices for creating and maintaining images. If you need help embedding them on our site, see Embed images.
We have four major categories of images on our site.
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.
- Alt text (required)
- Title (required)
- Surrounding text
- Annotations within the image
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).
Alt text doesn't apply to inline Feather icons.
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:
alt="Diagram showing the flow of data from client to server."
alt="Screenshot showing how to select a server."
alt="Photo of garden hose that serves as a metaphor for electrical amperage."
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.
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 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:
- Open SnagIt.
- In the Quick Styles pane, select the Theme gear icon.
- Select Import.
Because our translated mdx files in the i18n folder reference the same image folder that our English-language mdx files do, when image files are deleted or renamed, this can throw a build error because of the mismatch between the English files and the translated files. Here are some tips for deleting or renaming an image file:
- To replace an image: If you're replacing an existing image, you should give the image file the same name. Delete the file you want to replace and add the new file. Doing this means you won't need to change any references to that image file.
- To remove an image: If you want to simply remove an image without replacing it, don't delete the image file. Instead, just remove the import statement for that image file. The docs team occasionally runs a script that removes image files that aren't referenced by mdx files. This means we don't have to delete image files and so therefore have no need to touch the mdx files in the i18n directory, as they will be automatically updated with our translation workflow.
- To rename an image file: First, question if that's necessary to do. The image file name is generally unimportant and trivial. If you do decide to rename an image file, you must go into any mdx file that references the image file (including the i18n directory files) and update that file name.