The documentation nobody asked for that closed a board decision

I wrote documentation nobody asked for. It settled a decision worth thousands a month.

We tend to file “documentation” under chores. I have come to see the right kind of documentation as strategy in disguise. Two examples from the last five months.

1. The cost analysis

Nobody assigned it. I extracted real token budgets from our codebase, modeled build-vs-buy at scale, and packaged it so a non-technical leader could verify every number. It went up the chain, and the infrastructure decision was made on real data instead of a hunch.

2. The “why,” not just the “what”

The best doc I wrote about a tricky config did not just say what it did. It said why the value was set that way and exactly what would break if someone changed it. Without that note, the next engineer “optimizes” it and silently breaks things for a whole user segment.

The distinction that matters

Documentation written for the stakeholder reading now is a status update. Documentation written for the engineer who comes after you is high-value work. The second kind prevents the bug, closes the decision, and outlives you in the codebase.

Two rules I follow now:

1. Document the decision, not just the code. Capture the reasoning and the consequences of changing it.
2. If your doc lets a non-expert verify the outcome, you have written something that creates real organizational trust.