Examples turn abstractions into concrete cases that readers can copy, compare, or adapt, and they earn trust only when they actually run. A useful example is the shortest one that still demonstrates the documented behavior, with no unrelated features, decorative configuration, or copy-paste noise, and it should be tested in a fresh environment so the reader sees the documented result. Commands and snippets must be copy-pasteable, because trivial edits, placeholder names, or missing flags break trust quickly. "Show, don't tell" pays off especially for APIs and CLIs, where a real input and its output are more convincing than any amount of prose, and showing expected output also lets readers verify their own run, diagnose typos, and trust that the documented behavior matches reality.
Code blocks present runnable or copy-pasteable commands, configuration, or output with preserved whitespace and no prose wrapping around the syntax. Placeholder code that uses names like "my-host" or "TODO" is dangerous when the placeholders are not flagged, because a hurried reader will paste it literally; clearly marking placeholders keeps examples honest. Type signatures document the shape of a function while prose documents the meaning, and most well-documented code needs both. In Python and similar languages, a docstring is the literal string placed at the top of a function, class, or module to document purpose, arguments, return value, and exceptions, and it sits alongside the code rather than replacing it. Self-documenting code uses clear names and small functions to reduce the need for prose, but it is never enough on its own: intent, context, and trade-offs still need writing, and the most valuable kind of code comment is the "WHY" comment that explains the reasoning behind a non-obvious line, such as why a particular retry count was chosen over another.
Visuals clarify structure or sequence when text alone would be slower to understand, but they should earn their place. Screenshots are the right choice when the visual is the answer, such as locating a UI control or reading a diagram, and a reader would otherwise have to reconstruct the picture mentally from prose; they are the wrong choice for things code blocks or short text could say better, because screenshots are expensive to maintain and break the moment the UI changes. Diagrams model relationships or flow, with sequence diagrams for ordered messages between components and flowcharts for decision branches in processes like runbooks and troubleshooting trees. ASCII art is acceptable in code comments, READMEs, and terminal contexts where rendered images are not an option, when simplicity is the goal. Tables align parallel facts across rows so readers can scan a single column, while prose is better for sequential or causal relationships, single-row cases, or cells that would become paragraphs; a definition list is a lighter alternative for term-and-definition pairs like configuration keys. Every image needs alt text that describes what the image conveys rather than how it looks, and purely decorative images should have empty alt text. On mobile, long paragraphs, wide tables, and side-by-side code blocks break easily, so writing for narrow screens first and treating wide layouts as a progressive enhancement keeps docs usable everywhere.