diagramming

Topics in the source

• Diagramming
• 1. Decide the question, then pick the type
• 2. Pick one level of abstraction and stay there
• 3. Keep it under about nine boxes
• 4. Label the arrows
• 5. Write it in Mermaid
• 6. Keep it from going stale
• Don't set colours

A diagram earns its place by answering one question faster than a paragraph could. A diagram showing everything answers nothing — it is the visual equivalent of a page with no headings. Draw diagrams as code. A Mermaid block in the repository is diffable, reviewable, and edited by whoever changes the system. An exported PNG from someone's laptop is wrong within a month and nobody can fix it. Match the diagram to what the reader is asking: | Reader's question | Diagram | | --- | --- | | What are the pieces and how do they connect? | Component / C4 container | | What happens, in what order, between whom? | Sequence | | What states can this be in, and what moves it? | State | | How is the data shaped and related? | ER | | What are the steps and decisions? | Flowchart | | Who depends on whom for deployment? | Deployment | Choosing wrong is the most common failure. Component diagrams are drawn for questions that are really about ordering, and a sequence diagram would have answered them in half the space. Done when: you can state the one question this diagram answers. Mixing levels is what makes diagrams unreadable — a box for "Payments" next to a box for "validatecard()" gives the reade

This is an excerpt. Refer to the complete source and its current requirements.