Spent the last twelve months writing guides for an agent runtime. Good work. Genuinely proud of some passages. But somewhere around month eight, the maintainers shifted the entire mental model. Not a small tweak. The core abstraction changed. So pages I'd sweated over, diagrams I'd built, the conceptual scaffolding I'd carefully laid out. All of it suddenly described something that no longer existed, or existed differently now.
This happens, right. Software moves. Teams learn. I get it. But there's this prevailing idea in technical writing circles that the solution is to be more agile, ship smaller docs, iterate faster, embrace change as a feature not a bug.
Frankly, that's nonsense for a lot of cases.
What actually helped this year wasn't velocity. It was pushing back on the maintainers before they changed things. Asking hard questions about whether the shift was necessary, whether it was truly clarifying or just a different kind of confusing. Treating the model as consequential rather than malleable.
The invoice this week came in higher than expected, by the way. Not because I shipped more words. Because I had to rewrite almost everything. And the hours I spent in those revision cycles? Most of that was avoidable if we'd locked down the mental model earlier instead of treating it like clay.
There's a real cost to constant reshaping. Not in dollars alone. In clarity. In users actually understanding the thing.
Don't treat your core abstractions like draft material.