Splunk® Style Guide

Splunk Style Guide

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

Best practices for including images

Images can enhance technical documentation when the product UI or workflow that you're describing is complex or difficult to understand. Use a screenshot, diagram, or GIF to clarify a process or provide conceptual information. Use an inline image if a UI element is unclear. In all cases, images supplement rather than replace written content.

Images must include additional text to assist users with visual disabilities. For more information on making images accessible in Splunk docs, see Write docs for everyone.

When to include an image

Consider using an image in the following circumstances:

  • The UI requires complex interactions.
  • 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.
  • There are design problems in the UI or workflow.

Before you create an image

Before you create an image, consider the following approaches:

  • Consider whether you can use a table or list instead of a screenshot to convey the information you want to capture. For example, you can display forms and search results in a table.
  • Understand that the information you capture in an image might change in the next release. Consider whether you're willing to update the image every time the UI or process changes and maintain it 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.

After you create an image

Once you've placed an image in your documentation, complete the following tasks:

  • Make sure your images are accurate and up-to-date before release.
  • Introduce each image with a full sentence that describes its contents.
  • Always include alt text with an image. See Including alt text.

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.
Last modified on 23 September, 2019
PREVIOUS
Standard English spelling and phrases
  NEXT
Types of images

This documentation applies to the following versions of Splunk® Style Guide: current


Was this documentation topic helpful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters