4 ms·

How do you keep this up to date though? That's the biggest problem with documentation. Having some kind of append-only format, like ADR, can help, since the doc

How do you keep this up to date though? That's the biggest problem with documentation. Having some kind of append-only format, like ADR, can help, since the documentation specifically is tied to a decision at a single point in time. Still, those can drift from the actual implementation to the point where they are both misleading and confusing. Such is the entropic nature of software.

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 ago
  I 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 ago
  Oh, 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 ago
    I 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 ago
        He didn’t say future proof, he said low churn. These two things are radically different.
      - Tempest1981 6y ago
        When 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).
Uehreka 6y ago
That’s a fair point, although given how “high level” this is supposed to be, I’d imagine that needing to update it a lot might actually be a canary that the project in question is in a lot of flux.

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 ago
I 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 ago
Oh, 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 ago
  I 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 ago
      He didn’t say future proof, he said low churn. These two things are radically different.
    - Tempest1981 6y ago
      When 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).

Uehreka 6y ago

That’s a fair point, although given how “high level” this is supposed to be, I’d imagine that needing to update it a lot might actually be a canary that the project in question is in a lot of flux.