Skip to content

Documentation — Middle

Choose the artifact by question: tutorial for learning, how-to for a task, reference for facts, explanation for concepts, ADR for a durable decision, and runbook for operational action.

API docs define contracts and version behavior. Design docs frame context, goals, non-goals, options, risks, rollout, and observability. ADRs preserve why a consequential choice was made and what would trigger reconsideration.

Use diagrams for relationships and sequences that prose cannot show clearly. Keep names aligned with code and link to authoritative definitions.

Test yourself

  1. When is an ADR preferable to a code comment?
  2. Which artifact helps an operator during an alert?
  3. What makes an API example trustworthy?
  4. Which diagram best shows a failure sequence?

Continue to senior.md.