Your reviewer has eleven minutes. She runs the platform team at the client, she printed your deployment plan on the way into the room, and she opened it when the meeting started. At minute twelve someone will ask whether she approves. She will answer with whatever she absorbed by then.

Write the document for her. Most of us write for ourselves instead. We retrace the path we took: background, the constraints we hit, the options we weighed, and then, on page six, the thing we plan to do. That order matches how you learned it. It matches nothing about how she reads it.

Lead with the decision

Put the decision in the first paragraph and put its cost beside it. "We move the ingestion service to the new cluster over two weekends in September. Your team keeps the old cluster warm until October 3. We need one of your engineers on call for both cutovers." She now knows what you want from her, and she can spend the rest of the page deciding whether she believes you.

Everything after that paragraph answers her objections in the order she raises them. She wants to know what breaks during the cutover long before she wants to know which Kafka version you pinned. Sequence the doc by her questions, not by your reasoning.

Handle the rejected alternatives in two or three lines somewhere in the middle. You considered a blue-green swap and dropped it because the client's load balancer cannot hold two pools. Write that sentence and move on. The comparison matrix you built over an afternoon serves you, not her.

Put the diagram where the question appears

Engineers pile their diagrams at the end under a heading called Architecture, or exile them to an appendix. The reader hits a paragraph about failover on page four, flips to page nine, loses her place, and reads neither.

Put each diagram under the paragraph that raises the question it answers. When you write "the cutover holds both clusters live for six hours," she wants the traffic picture right there, in the same eyeful as the sentence. On paper she cannot click a link and click back. She has one hand on the page and one on her coffee.

Apply that in reverse too. If a diagram has no paragraph that needs it, delete the diagram. You drew it while thinking, and your thinking tools do not belong in her copy.

One diagram, one idea

The worst picture in most design docs tries to be the map of the whole system: twenty boxes, dotted lines for the async calls, a legend, a floating box labeled "monitoring." You drew it over an hour, you can read it, and she cannot read it in forty seconds.

Split it by question. One picture covers the canary going bad.

flowchart TD
    A[Canary takes 10% of traffic] --> B{Error rate under 0.5% for 15 min?}
    B -- Yes --> C[Shift to 50%]
    B -- No --> D[Roll back to previous revision]
    C --> E{Still clean after 30 min?}
    E -- Yes --> F[Full rollout, old revision scaled to zero]
    E -- No --> D
    D --> G[Page the on-call, old revision keeps serving]

A second one covers who calls whom during a release.

sequenceDiagram
    participant Eng as Release engineer
    participant CI as CI pipeline
    participant Reg as Image registry
    participant K8s as Cluster API
    Eng->>CI: Tag release v2.4.0
    CI->>Reg: Push signed image
    CI->>K8s: Apply new Deployment
    K8s->>Reg: Pull image
    K8s-->>CI: Rollout status
    CI-->>Eng: Green, or red with the failing pod

The two shapes do different jobs. Reach for a sequence diagram when the reader asks who calls whom, and in what order. The lifelines carry time down the page, so she sees that the cluster pulls the image after CI applies the manifest, which is the ordering that bites you when the registry credentials expire.

Reach for a flowchart when she asks what happens when. Branches carry conditions, and conditions are where she finds the gap you missed. A platform lead reading that canary chart will ask what happens if the error rate sits at 0.6% for four minutes and then recovers. You want that question, and she found it in nine seconds because the picture held one idea.

Stack both ideas into one drawing and she gets neither. She sees a wall, decides to ask you in the meeting instead of reading, and now you are the doc.

Write the caption you would say out loud

Under each diagram, write the sentence you would say while pointing at it. "If the canary stays clean for fifteen minutes we go to half traffic, otherwise we roll back and page your on-call." She reads the caption, glances at the picture to confirm it, and keeps going. Without the caption she stares at boxes and reconstructs your intent from arrow directions, which costs her thirty seconds she does not have.

You will catch your own mistakes writing them. If you cannot cover a diagram in one sentence, it holds more than one idea, and you should cut it in half before she has to.

Keeping the paper version honest

I keep the prose and the diagrams in one Markdown file, with the diagrams as fenced mermaid blocks sitting between the paragraphs they belong to. Moving a diagram means moving six lines of text, so the pictures stay where I put them. Markdown With Diagrams renders that file as I type and exports it to A4 with the text selectable and the diagrams as vector, so the printout in the platform lead's hands matches what I saw on screen. Nothing goes to a server and there is no account to make.

The test before you send it

Hand the draft to an engineer on your own team who knows nothing about the client. Give them two minutes, take the paper back, and ask two questions: what am I proposing, and what does it cost them? If your teammate answers both, the platform lead will too. If your teammate hedges, your decision is still on page six, and no amount of diagram polish will move it forward.