# Describe architecture diagrams as relationships, not shapes

Canonical: https://githtml.com/guides/text-descriptions-for-architecture-diagrams
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

Describe the components, direction of information flow, important boundaries, and exceptional paths that the diagram communicates. Put the full explanation in visible HTML near the visual, with a short alternative that identifies it. A useful description preserves the system's meaning without requiring readers to reconstruct every box and arrow.

## Identify the diagram's essential message

An architecture diagram can communicate sequence, ownership, trust boundaries, or dependencies. Determine which of those matters to the surrounding discussion. A migration review may care most about which component changes, while a reliability review may focus on retries and failure isolation. Describe the relevant relationships rather than narrating the picture from its top-left corner.

List the components using the same names as the diagram and the rest of the document. Inconsistent labels force readers to decide whether Worker, Processor, and Job service refer to one component or three. Explain abbreviations on first use, especially when the document may be read outside the team that created it.

## Use structure for complex explanations

A single enormous alternative-text attribute is not a good place for a multi-stage system description. Use paragraphs, an ordered sequence, or a small table in the visible document. That structure helps everyone inspect the explanation, including readers who can see the diagram but struggle with its density on a phone.

For example, describe the normal request path first: the client submits work, the gateway validates it, the queue stores the job, and a worker writes the result. Then describe a failure path separately. If an arrow crosses a boundary that matters, explain what changes at that boundary. Do not assume line color or dashed styling communicates the distinction by itself.

## Check equivalence, not visual imitation

A text description does not need to reproduce the exact arrangement of shapes. It needs to preserve the facts required to understand the report. Ask a reviewer to answer the same architectural question using only the text. If they miss a dependency or exception that changes the conclusion, add that information rather than adding more spatial adjectives.

1. State the diagram's purpose in a short introductory sentence.
2. Name every component needed for the argument.
3. Describe the normal flow in order.
4. Explain retries, failures, and trust boundaries separately.
5. Include relevant numbers or conditions as text.
6. Keep the description adjacent to the diagram or provide a clear same-document link to it.

## Sources and further reading

- [W3C WAI: complex images](https://www.w3.org/WAI/tutorials/images/complex/)

## Related guides

- [Keep an HTML report readable when text is enlarged](https://githtml.com/guides/zoom-and-reflow-html-reading)
- [Make report statuses understandable without color](https://githtml.com/guides/status-labels-without-color-dependence)
- [Check keyboard navigation in a static HTML report](https://githtml.com/guides/keyboard-navigation-static-html)
- [Give document navigation enough space for touch](https://githtml.com/guides/touch-friendly-document-navigation)

Editorial approach: https://githtml.com/guides/about