The SMIG Rule: Situation, Mechanism, Implication, Gotcha
Stop writing docs that just say "this function adds two numbers." A comment or walkthrough step that narrates the code adds zero information — the reader is already looking at the code. Nobody re-reads what the code already shows. Good onboarding spends its words on the parts you cannot see: why it's built this way, what breaks if you touch it wrong. The SMIG rule is a checklist that forces every doc step to earn its space.
The four parts
Write every step of a doc, code tour, or onboarding guide against four questions:
| Part | Question it answers | Example line |
|---|---|---|
| Situation | What are we looking at? | "This is the retry loop that wraps every outbound payment call." |
| Mechanism | How does it work? | "It backs off exponentially: 1s, 2s, 4s, capped at 30s." |
| Implication | Why does it matter? | "Without the cap, a dead gateway would stall checkout for minutes." |
| Gotcha | What bites you? | "The retry is NOT idempotent-safe — never wrap charge() calls in it." |
Situation and Mechanism should be short — one line each is usually enough, because the code carries most of that load. Implication and Gotcha are where the invisible knowledge lives, so that's where the word count goes.
Why "adds two numbers" docs fail
Code already answers what and (mostly) how. What it can never answer:
- The rejected alternative. "We tried a queue here first; it deadlocked under load." One sentence saves the next engineer a week of rediscovery.
- The blast radius. Which callers depend on this behavior? What breaks two services away?
- The trap. The parameter that looks optional but isn't. The function that's safe everywhere except in a transaction.
A useful smell test: if you deleted the code and kept only your doc, would the doc still say anything? "Adds two numbers" says nothing. "Rounds half-cents toward the merchant per the 2019 billing audit" survives.
Google's technical writing course frames the same idea as an equation: good documentation is the knowledge your audience needs minus the knowledge they already have. For a reader with the code open, Situation and Mechanism are mostly "already have" — Implication and Gotcha are the gap.
Budget your words like a reviewer budgets attention
- Situation: 1 sentence. Orient, don't tour.
- Mechanism: 1–2 sentences. Only what the code obscures (concurrency, ordering, hidden state).
- Implication: 2–3 sentences. Consequences, dependencies, the "or else."
- Gotcha: as many as you honestly have. This is the section people screenshot.
If a step ends up 80% Situation and Mechanism, either the code needs a rename more than a doc — or you're narrating.
Power user: SMIG is a prompt, too
The rule doubles as an instruction for AI coding assistants. Ask your assistant to "write a code tour of this module where every stop covers Situation, Mechanism, Implication, and Gotcha" and you get structurally better output than "document this code" — because the model, like a junior engineer, defaults to narrating what it sees. The rubric forces it to reason about consequences and edge cases instead.
- CodeTour (VS Code): record a guided walkthrough where each stop is one SMIG block; the tour plays back inside the editor, next to the live code.
- Review gate: when a doc PR comes in, comment "where's the G?" on any step with no gotcha. Either a real one appears, or the author confirms the step is genuinely trap-free — both outcomes are wins.
And keep it minimal: Google's documentation best-practices guide calls this "minimum viable documentation" — a small set of fresh, accurate docs beats a sprawling assembly of docs in various states of disrepair.
Resources
- Audience — Google Technical Writing One (the "needed minus known" equation)
- Documentation Best Practices — Google style guide (minimum viable documentation)
- Explanation — Diátaxis (the doc type for context and "why it matters")
- A beginner's guide to writing documentation — Write the Docs
- CodeTour — record and play back guided walkthroughs in VS Code
Building an AI feature? Yeda AI designs, audits, and ships production LLM systems.