Figure and Image Elements
Use the figure element to insert images and associated elements into your topics. Images add value to your content and can help convey complex ideas.
Figure Element
The figure element can nest the following elements:
- title element
- image element
- alt element
Guidelines
- If you use figures in a task topic to explain a
step, nest it inside another element first.
For example, insert a figure in the information element, step result element, or step example element.
- Nest the title element inside the figure element only if it adds value.
For example, there is no need to add titles if you use figure to explain a step.
- Nest the alt element inside every image element to make your content more
accessible.
For example, the image description that you provide in the alt element can be processed by screen readers.
Title Element Guidelines
- Insert title element only if it adds value to your content
- Be descriptive but keep the title short and simple
- Use title case
Image Element Guidelines
- Assume a file naming convention. For example, category_object_illustrated.extension (pdf_generator_editor_left_pane.png).
- For static images, use the PNG format so that the images can be used in different screen sizes and for a variety of publishing outputs like HTML, PDF, etc.
- For animated images, use the GIF format. For more information, see Animated Images.
- If you want to annotate an image, set the annotation color to #FF0000 (red).
- If you want to insert an inline icon, do the following:
- If possible, resize the icons to 16x16 px
- Use the image element alone (do not encapsulate it in the figure element)
- Set the image element placement attribute to the inline value
Alt Element Guidelines
The alt element provides alternative text for an image. This element is critical to make your content accessible. For example, the alt element content can be processed by screen readers.
- Do not use directional language, such as “above”, “next to”, “beside”, etc.
- You may need to provide some contextual information in the image description
- Describe the relevant parts of the image in the same way you would verbally describe the image to someone
- In some cases, along with the image description, explain why an image was included
Animated Images
You insert GIFs to your topics by using image elements.
Guidelines
- Treat GIFs as additional and optional aids to your textual content. Your documentation should be understandable without any graphical aids.
- Include GIFs only into online deliverables. If you plan to publish a given asset both as an
online and printed deliverable, include a static image equivalent into printed
deliverables.Tip: Assign the
@audience="print"attribute to the static image and the@audience="online"attribute to the animated image. Use an appropriate DITAVAL when publishing your asset. - Crop your GIFs so that they only show the relevant part of the interface that you capture.
- If you capture a web-application, use the zoom feature built-in your web-browser as much as possible.
Requirements
You can use the software of your choice to capture GIFs. However, ensure that your captures meet the following requirements.
| Category | Requirement |
|---|---|
| Frame rate | 30 Frames Per Second (FPS) |
| Transition type | Fade |
| Transition length | 10 frames |
| Effects (for example, highlighted mouse clicks) | No |