explain-visually
Explain Visually
Create a human-facing HTML artifact that explains a technical design visually. Beauty serves clarity. The reader should understand what the system is, how it operates, and the important implementation contracts well enough to retell it after a one-to-two-minute read.
Workflow
1. Understand
Read the source material. Identify the audience, core idea, moving parts, decisions, tradeoffs, data contracts, and what the human should remember.
Assume a mixed audience by default: team members who need implementation detail and external readers who lack local context. Make the artifact self-contained. Expand project-specific acronyms once, explain why each major component exists, and avoid relying on tribal knowledge.
Ground the explanation in facts from the source. Prefer concrete names, paths, commands, interfaces, schemas, examples, and observed behavior over positioning language.
Default to explaining for a smart technical reader who is new to this system. Define jargon before using it. If a term needs domain context, replace it with plain language or explain it visually.
Set a strict reading budget: the full artifact should be scannable in one to two minutes. Prefer a small number of high-signal sections, short paragraphs, and tables that can be skimmed. Omit background that does not change the reader's mental model or implementation decisions.