Posts
Notes on Maintainable Technical Writing
A few principles for writing technical notes that remain useful after the original context fades.
A technical note is easier to maintain when a future reader can understand why a decision was made, not only what was changed.
Explain the shape of the problem
Good documentation gives enough context to establish the problem, the constraints, and the intended outcome. This makes the solution easier to evaluate when the system or its assumptions change.
Prefer useful boundaries
A note does not need to explain everything. It needs to explain the parts that are difficult to infer from the code: the tradeoffs, the rejected alternatives, and the conditions under which the decision should be revisited.
The result is writing that remains useful to someone who was not present when the original decision happened.