Technical documentation
On this page 8 topics
Overview
Topics
- ADRs
- RFCs
- sequence diagrams
- C4 diagrams
Learn first
3 h of practice (estimate)
Learning outcomes
- Write ADRs capturing context, options, decision, and consequences.
- Write an RFC/design document for a change that needs review before building.
- Draw C4 context, container, and component diagrams and sequence diagrams as code (Structurizr, PlantUML, or Mermaid).
- Write an operational runbook for a known failure.
Lessons
Lab and exercises
Lab
MID-063-LAB1 · Shop docs
Outcomes: 1–4 · Time: ~3 h
- Produce C4 level 1, 2, and 3 diagrams as code, with titles and legends.
- Draw sequence diagrams for the order saga: happy path and one compensation path.
- Write ADRs for the five biggest Shop decisions, each with real alternatives and consequences.
- Write runbooks for three alerts.
- Give the docs to a peer unfamiliar with Shop with ten questions.
Acceptance: the peer answers the ten questions using the docs alone.
Exercises (assessment: documentation review; five exercises)
| ID | Outcome | Task |
|---|---|---|
| MID-063-EX01 | 1 | Review a diagram without a legend; list five things a reader cannot know and fix them. |
| MID-063-EX02 | 1 | Write an ADR for "outbox instead of dual writes", with at least two alternatives and consequences. |
| MID-063-EX03 | 2 | Write a one-page RFC outline for adding returns and refunds to Shop, including goals, non-goals, and rollout. |
| MID-063-EX04 | 3 | Draw a C4 container diagram of Shop as code and a Mermaid or PlantUML sequence diagram for payment failure. |
| MID-063-EX05 | 4 | Write a runbook for the alert "consumer lag above threshold for 10 minutes". |
Show solutions
- EX01 Unknown: meaning of shapes, sync versus async, technology, owner or date, scope. Fix with a legend, labeled arrows, title, and date.
- EX02 Context: dual writes can lose events. Options: outbox, two-phase commit, best-effort publish. Decision: outbox. Consequences: relay to run, at-least-once delivery so consumers are idempotent.
- EX03 Problem, goals, non-goals (for example no marketplace refunds), proposal, alternatives, risks, rollout in slices, open questions, reviewers and deadline.
- EX04 Containers: web, gateway, orders, inventory, payments, Postgres, Kafka with labeled arrows; sequence shows
PaymentFailedthenReleaseStock. - EX05 Symptom, impact, check lag dashboard and consumer logs, scale or restart consumer, check poison message and dead-letter topic, verify lag falls, escalation contact.
Quiz
Outcomes: O1 ADRs · O2 RFCs and design docs · O3 C4 and sequence diagrams as code · O4 runbooks.
A self-check for you: nothing is graded, saved or sent anywhere. Choose an answer, then check it. You can try again as often as you like.
Practical part
Five exercises MID-063-EX01 to EX05 plus the lab. Pass: documentation review with no missing legends or alternatives, and a peer answering the ten questions from the docs alone.
Common mistakes
Diagrams with no legend; ADRs written after the fact without the alternatives.
Assessment
Documentation review (COM dimension).
Career relevance
Architecture documentation (SRC-010) and solution documentation (ARC-043).