I thought about this too recently. I guess documenting every consideration along the way would take way too much time (would be longer than the documentation of actual implementations), but one of these days this seems likely to change?
That day is now and the reason is that the documentation doesn't have to be written anymore.
The conversation that led to the decision already exists — in your PR comments, Slack threads, and tickets. The reasoning is already there. It just needs to be extracted and structured automatically, not written from scratch.
That's the shift that makes this viable in 2026 when it wasn't in 2020. LLMs can read the noise and surface the signal. Zero extra time from the developer.