Hacker News new | ask | show | jobs
by jayd16 2136 days ago
So this is somewhere between code comments and Confluence pages. Seeing as even comments can get stale, how accurate do these docs stay?

The added focus on "why" instead of "what" seems more resistant to cruft.

4 comments

>Seeing as even comments can get stale, how accurate do these docs stay?

Part of the idea is that they're immutable, append-only. They express why an architecture / decision was made, when it was made.

Not that it takes anything away from your point, but to be slightly more precise, the content should (probably, see below) be treated as immutable. The metadata, included in the same files, is mutable - things like status, related ADRs, superseding PRS, etc.

Above I said probably - I'm not sure that we shouldn't allow editing when it's purely clarification, communicating more clearly what it already communicated to most of the audience.

An append-only section for adding further observations, as the decision plays itself out, is also an interesting option, although I don't know whether it would actually be more valuable than distracting.

They are not supposed to be updated. It captures a decision at one point in time with lots of context.

If an update is necessary, you create a new ADR.

If comments on the same line (or an adjacent line, such that it shows up in `git diff` output and the default code review display) get stale then that is a pretty bad failure of both the programmer and the reviewer(s); in my experience that doesn't happen very often.

A much bigger issue is comments that are a few lines (or a few tens of lines) away from some piece of what they're talking about. Then, they suffer from exactly the same issue as documentation anywhere, inside the repo or out: something drew the developers attention to the code that needed to be changed, but then there was no reason they should have known to look in this particular other location for text talking about what they changed. That's not the programmer's fault, unless we want our programmers to take the time to review every piece of documentation for anything that might need to be changed. I'd guess there are some contexts where that's appropriate, but I haven't ever worked in one.

Alternatively, we could have it be someone's job to own the docs, continually run over them and make sure they still apply, and stay abreast of PRs as they merge. I haven't seen that tried - it might be valuable if it was a role someone wanted.

What I've been trying is adding cross-references to my code, so that something can always be visible on the line or a neighboring line that notes that there's something relevant in another place. This is then checked in CI for integrity, and references that appear in the diff have their referents surfaced on the PR for the benefit of the reviewer. So far the links are pretty sparse, but have already been somewhat valuable. I intend to piggyback on the same system as I introduce ADRs.

I'd like to release the above tooling as F/OSS but really the trickiest parts are CI integration. The check is literally piping git diff to grep, looking for things of the form ^^{some label} and finding the associated @@{some label}. I decorate the PR on github with annotations through the Git Checks API.

Yes, I think of them as blogs. New engineers can read along and see the evolution of thoughts and design decisions.