5 ms·
Revise it twice a year. If the document gets stale faster than that, just delete the stale bits: they are probably too low level for this kind of documentation.
by matklad 6y ago
Revise it twice a year. If the document gets stale faster than that, just delete the stale bits: they are probably too low level for this kind of documentation.
- simonw 6y agoI find filing issues whenever I find out-of-date docs helps. They tend to get fixed pretty quickly, because they offer a nice change of pace from working on bugs or features.
- amw-zero 6y agoOh, so the solution is to just add another thing to “remember” to do. That must be what I’ve been missing all these years. Yes, that’s extra thick sarcasm.
- matklad 6y agoI disagree with this characterization. ARCHITECTURE.md is specifically engineered to be low churn, so in this respect it is meaningfully different from other “keep docs” advise. In practice, I personally didn’t find it difficult to maintain half-decent ARCHITECTURE.md, and I am not at all good with keeping the docs otherwise.
- amw-zero 6y ago> specifically engineered to be low churn This is not actually possible. You're kidding yourself if you think such a document is "future proof."
- chrismorgan 6y agoHe didn’t say future proof, he said low churn. These two things are radically different.
- Tempest1981 6y agoWhen doing code reviews, someone will usually say, "we need to update the docs" if it's a big change. If you can't do that now, file a bug to remind yourself, or assign it to the new guy (maybe kidding).