Tables and Images
Use tables and images as information structures, not as decoration.
Tables and images are easy to use as visual filler, but in documentation they should serve information design. Tables are for comparisons, parameters, states, and fields. Images are for screenshots, diagrams, and visual support. Both should help readers understand faster instead of adding friction.
Steps
- Decide whether the information is comparable or visual
- Make table headers and image context understandable on their own
- Add alt text and surrounding context for images
- Do not hide primary text content inside screenshots
Decide whether the information is comparable or visual
If the content is about fields, parameters, version differences, roles, permissions, or state matrices, prefer a table. If the content depends on UI layout, visual state, workflow screenshots, or diagrams, prefer an image. Do not turn inherently tabular information into a screenshot of text.
Make table headers and image context understandable on their own
A table should have meaningful column headers so readers can roughly understand it even before reading all surrounding prose. An image should come with enough explanation to tell readers what the image proves or illustrates, instead of dropping it into the page without context.
Add alt text and surrounding context for images
An image should not rely on visuals alone. Add alt text where possible and explain the image in nearby prose. For public sites and AI consumption, clearer image context means the content is less likely to become an isolated visual island that only works for direct human viewing.
Do not hide primary text content inside screenshots
Long textual explanations, config values, or commands should not primarily live inside screenshots. Information that needs to be searched, copied, indexed, and machine-read should still live in prose, tables, or code blocks. Images are better as supporting evidence than as the only source of truth.