Are there best practices for using images in DITA documentation?

Best practices for using images in DITA documentation are essential for creating effective and user-friendly content. These practices ensure that images enhance content clarity, maintain consistency, and are accessible to all users.

Some best practices in using images in DITA include relevance and clarity, image quality, consistency, alternative text for accessibility, file management, copyright and licensing, labeling and captions, localization considerations, and testing and feedback.

  • Relevance and Clarity: Images should directly support the content and add value. Each image must serve a specific purpose, whether it’s illustrating a concept, guiding users, or providing a visual reference.
  • Image Quality: Images should be of high quality, ensuring that details are clear and easily discernible. Use appropriate resolution and consider aspects like aspect ratio and image format (e.g., PNG, JPEG, or SVG) based on the intended use.
  • Consistency: Maintain visual consistency throughout the documentation. Use a consistent style, size, and alignment for images. Ensure that images don’t appear disproportionate or unrelated to the surrounding content.
  • Alt Text for Accessibility: Include descriptive alternative text (alt text) for each image to make the content accessible to users with disabilities. Alt text should convey the content or purpose of the image.
  • File Management: Organize image files in a structured manner. Use meaningful file names and directories to facilitate easy retrieval and maintenance.
  • Copyright and Licensing: Respect copyright and licensing rules for images. Content creators should ensure that they have the rights to use the images, especially in commercial documentation.
  • Labeling and Captions: Use clear labels and captions for images to provide context. This helps users understand why the image is relevant and how it relates to the content.
  • Localization Considerations: When preparing images for global audiences, consider localization needs. For example, text within images may need to be translated, so ensure it’s editable or that multiple versions exist for different languages.
  • Testing and Feedback: Test documentation with users or colleagues to gather feedback on the effectiveness of images. Adjust images as necessary based on the feedback received.


In a software user manual, there is a need to explain the process of customizing the user interface. An image is included to demonstrate how to rearrange buttons.

  • Relevance and Clarity: The image should be relevant to the section explaining user interface customization and clearly show the button rearrangement process.
  • Image Quality: The image must be of high quality with clear visual details of the interface.
  • Alt Text for Accessibility: Alt text should describe the content and purpose of the image, aiding users who rely on screen readers.
  • File Management: Organize image files within the documentation project folders for easy access.
  • Localization Considerations: If the manual is for a global audience, ensure that any text within the image is editable or that different versions are available for different languages.