Tables, images, and diagrams
Always add descriptive text
Every table, image, and diagram in an article should be accompanied by text that describes what it shows and what conclusion the reader should draw from it.
That text serves two audiences: For AI, it is the only way the meaning becomes retrievable; for humans, it reinforces the visual and helps readers who scan quickly, those who use screen readers, or people who view the page on a device where the visual does not render well.
Tables
Introduce the table before it appears. Write a short paragraph before the table that explains what the table contains and what the reader can learn from it.
Example:
Before: An article drops a three-column pricing table onto the page with no lead-in and no follow-up. A customer asking "which plan supports single sign-on?" gets an AI response that cannot reliably answer the question, because the AI processed the table cells but lost the relationship between plan names and features.
After: "The following table compares our three subscription plans. The Basic plan is designed for individuals. The Team plan supports up to 50 users and adds shared workspaces. The Enterprise plan adds single sign-on, a dedicated account manager, and custom contracts. [table follows]"
The "after" version gives the AI a paragraph it can retrieve and use even when the table's structural meaning is lost in processing. It also front-loads the key differences so a scanning reader gets the answer without studying every cell.
Keep tables simple
- Use clear, short header labels that are no more than a few words.
- Give every cell a real value. Empty cells confuse both readers and AI.
- Keep cell contents short. If a cell needs a long explanation, that content belongs in prose.
- Do not nest tables inside tables.
- Avoid putting bulleted lists inside cells.
- Do not rely on formatting (colors, bold, icons) to convey meaning. If a row is important, say so in the text.
Images and screenshots
Images can illustrate a concept, but AI will not see them. What the image communicates also needs to be present in the text around it.
- Caption every image with a sentence to describe what it shows.
- Describe the key content in the article body, not only in the caption.
- Use images to reinforce the text, not to replace it.
Example:
Before:Click the settings icon. [screenshot of the settings icon]
If the reader does not recognize the settings icon in your product, this instruction is useless. AI cannot describe the icon to a customer asking where it is.
After:Click the settings icon, which is a gear-shaped icon in the top right corner of every page. [screenshot of the settings icon, with caption: "The settings icon appears in the top right corner of every page."]
The location and appearance of the icon are in the text. A customer who asks "where is the settings menu?" can be matched to this article, and AI can describe the icon's location in a response.
Diagrams and flowcharts
Diagrams often contain the most complex meaning in an article: a workflow, system architecture, a decision tree. They are also the most invisible content to AI.
If you include a diagram, describe the flow in prose alongside it. The diagram supports the prose; it does not replace it.
Example:
Before: An article includes a flowchart showing the approval process for expense reports, with no accompanying description. A user asks "who approves my expense report?" and AI cannot answer reliably.
After: The article includes the same flowchart, preceded by: "Expense reports follow a three-step approval process. Your direct manager approves first. Reports over $500 then go to your department head. Reports over $5,000 then go to the finance director. If any approver rejects the report, it returns to you with comments." [flowchart follows]
The AI now has the full process in text, and the diagram is available for users who prefer a visual overview.