Documentation & knowledge
Why Is That 0 Ω Resistor There? Documenting Design Rationale
Files record what, never why. Which decisions deserve a written reason, where it should live, a five-line format, and the four costs of not having any.
There is a 0 Ω resistor on the board, bridging two ground areas. It serves no electrical purpose that anyone can see.
A new engineer has three options. Leave it, and never know why it is there. Remove it, and find out the hard way. Or spend a day reading old emails looking for the answer, which is what usually happens, and which usually fails.
That resistor is a decision someone made for a reason. The decision survived; the reason did not. Multiply it across a few hundred components and several years and you have the ordinary condition of most hardware projects: a design that works, that nobody fully understands, and that therefore nobody can safely simplify.
The questions a design cannot answer about itself
Files record what. They are silent on everything else:
Why this part and not the cheaper equivalent? Why is this trace routed the long way round? Why is there a footprint here with nothing in it? Why is this test point where it is? Why 4k7 and not 10k, when either would work? Why was the obvious approach not taken?
Each has an answer. The answer was obvious to the person at the time, which is exactly why they did not write it down, and why nobody can reconstruct it afterwards.
The three kinds of rationale, and only one needs effort
Not everything deserves a written reason. Most decisions are routine and self-evident from the design.
Routine. A decoupling capacitor next to a power pin. No explanation needed; the convention explains it.
Considered but conventional. A pull-up chosen as 4k7 because of bus speed and capacitance. Worth a single line in the schematic as a note, not a document.
Non-obvious or counter-intuitive. The 0 Ω link. The part that costs four times the alternative. The footprint left empty. The approach that looks wrong and is not. This is the category that needs writing down, and it is a small fraction of the decisions in any project.
A useful test: would someone competent, seeing this for the first time, be tempted to change it? If yes, write the reason. If no, leave it alone. That single question keeps the volume manageable, which is what determines whether the habit survives.
Where the reason should live
There is no single right home, and the trade-off is between proximity and space.
| Place | Good for | Limit |
|---|---|---|
| Schematic text note | Anything tied to a specific net or part | No room for reasoning |
| BOM comment column | Why this part, why this alternative | Short, and easily lost in export |
| Silkscreen | Almost nothing | Permanent, tiny, costs board area |
| Change record | Why something changed | Only covers changes, not original decisions |
| Design notes document | Reasoning, alternatives, trade-offs | Far from the design; goes stale |
The practical answer is usually both: a short marker where the decision is visible, pointing at a longer explanation elsewhere.
A note on the schematic saying R45: 0R link, see design note 7 — do not remove is worth more than either half alone. It is seen by the person who would otherwise delete the part, and it tells them where to look.
A format that people actually fill in
Long templates do not get used. This one fits in five lines:
Decision: R45, 0 Ω link between analogue and digital ground. Date: 2024-06-11 Alternatives considered: solid connection; ferrite bead; full isolation. Reason: single-point ground required for ADC noise performance; measured 14 bits effective with the link, 11 without. Ferrite bead rejected on cost. Constraint: do not connect the planes elsewhere.
Sample content. The two fields that earn their place are alternatives considered and constraint. Alternatives stop the next person re-evaluating ground they have already covered. The constraint says what must not be done, which is the part that prevents the expensive mistake.
Write these as you go. Rationale written at the end of a project is reconstruction, and it is usually wrong in the places that matter most, because the reasoning that felt obvious has been overwritten by the outcome.
What this is not
It is not a design review record, and it is not a change log.
A change record says we moved from Rev B to Rev C because the regulator overheated. That is the history of a change. Rationale explains why the design is as it is now, including the parts that have never changed — which is precisely the knowledge a change record never captures, because nothing ever happened to those parts.
They complement each other. If you keep change records already, rationale is the gap they leave.
The cost of not having it
The absence shows up in four ways, and only the first is obvious.
Archaeology. Hours spent working out why something is the way it is, every time someone new touches the design.
Regression. The 0 Ω link gets removed in a cost-reduction pass. The noise problem comes back, and nobody connects the two events.
Paralysis. The opposite failure, and more common. Nobody dares change anything, because nobody knows what is load-bearing. The design ossifies and accumulates cost nobody can justify removing.
Repetition. The approach rejected in year one is proposed again in year three, investigated again, and rejected again for the same reason.
Paralysis is the one that quietly costs the most. A project where every odd decision is explained can be simplified; one where none of them are can only be added to.
Where to start, if you have none of this
Do not try to document an existing design retroactively. It is a large job and the output is mostly guesswork.
Start here instead: write the reason for the next non-obvious decision you make, in five lines, next to the thing it concerns. Then the one after that.
Within a year the parts of the design that are actively changing will be the parts that are explained, and those are the parts that need it.
Rationale is only useful if it can be found from the thing it explains, and stays attached to it as revisions accumulate.
Notes in XKEMA travel with the board and the component records they belong to, rather than living in a separate document that has to be found first.
Hardware documentation How to organise hardware engineering documentation * Hardware project handover