Every team I've talked to over the past few months has some version of the same story. A new hire joins, gets pointed at Confluence or Notion, and finds pages that are technically accurate and completely useless for understanding why anything is built the way it is.
Nobody set out to make bad docs. The docs were fine when they were written.
The problem is nobody links the doc for the payments refactor to the incident that caused it, or the Slack thread where the actual tradeoff got argued out. Six months later that context is gone even though the doc is still sitting there.
I started digging into how teams actually lose this and it's a smaller list of causes than I expected. Writing it up here.
Top comments (0)