Best practices for including images

Images clarify complex UI or workflows in technical documentation. They should supplement, not replace, written content and include alternative text for accessibility.

Use a screenshot, diagram, or GIF to clarify a process or accompany conceptual information. Use an inline image to display an icon if a UI element is unclear.

Note: All images must supplement written content. Don't use an image as a replacement for writing out a process or a concept. Images must also include surrounding and alternative text to assist users with visual impairments.

When to include an image

Consider using an image in the following circumstances:

  • A workflow is difficult or complicated to process by words alone.

  • You need to orient users to a screen that has many functional parts.

  • You need to illustrate complex relationships among discrete parts of a product.

  • You need to diagram or illustrate conceptual information.

  • You need to illustrate several steps in a complex or intricate process.

  • The UI requires complex interactions.

  • The design of the UI or workflow isn't intuitive and you think users might need extra help.

  • You need to supplement the name of a UI element in text with a visual aid from the UI.

When to avoid including an image

Avoid the following uses and types of images in your documentation:

  • Don't include an image to replace or avoid writing an explanation about how to complete a task.
  • Don't include a screenshot of the UI if the user can follow your written instructions without it. A well-designed UI doesn't need an accompanying screenshot in the documentation.
  • Don't use photographs in your docs.
  • Don't include an image if it contains customer data or Splunk data.

Before you create an image

Before you create an image, follow these approaches:

  • Consider whether you can use a table or list to convey information instead of a screenshot or diagram. For example, you can display forms, search results, or parts of a process in a table.
  • Understand that the information you capture in an image might change in a future release. Consider whether you're able to update the image every time the UI or process changes as well as maintain the image for every release.
  • Whenever possible, reuse an existing image instead of creating a new one. Consider whether you can use the same image for multiple steps or procedures.
  • When you create a screenshot, capture the UI while using the light theme with your screen zoomed to 100%. If possible, don't capture the UI using the dark theme.
  • When you use a screenshot from the UI, check that the image doesn't show sensitive information, like customer data or Splunk data.

After you create an image

After you place an image in your documentation, ensure you follow these guidelines:

  • Introduce each image with a full sentence that describes its contents.
  • You can include an optional title with an image. Do not include enumeration in the title. Numbers lose context if an image is reused.
  • Always include alt text with an image.

    For more information on making images accessible in Splunk docs, see Using images with accessibility.

  • Make sure your images are accurate and up to date before release.