This is far from the first time I've evangelized this paper here on HN... but I think the ideas of the OP and the Naur paper "Programming as Theory Building" have a high degree of overlap. Indeed, at some level, the Naur paper deals with identifying the problem while the OP deals with practices to bridge the knowledge gap identified in the paper.
Why Write ADRs
11–20 of 64 posts
Re: Why Write ADRs
#12So 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.
Re: Why Write ADRs
#13So 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.
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.
Re: Why Write ADRs
#14These articles about engineering process always put the responsibility solely in the implementing engineer's lap. Always more and more work to achieve JPL-level capability maturity, no matter your budget or headcount. Of course we want unit tests for every case, and verbose explanation in every atomic commit message, and architecture documents that are seldom read before they become stale. But make sure you also get…
what you mention are real pain points, though from my experience they actually were a lot simpler than locking info away in some external tool. there is very little additional cognitive cost with adr's and from what I've experienced they add other value too such as a record of why things were done which saves a lot of time when you're ramping up and onboarding new team members who have a tendency to discuss why things are done in a specific way and not another. when used correctly they're not just another thing to take care of but an actual time saver (have personally avoided many meetings by simply pointing new people to them - and they have the benefit of structuring and capturing the architecture discussions in a central place right next to your code ... (if the git log history isn't enough for us we use gitlab comments on changes the same way we would use it on code). it's brilliant because it's so simple imo.
Re: Why Write ADRs
#15The basic idea is good, but isn’t a commit message the best place for this? That will ensure that people will find it when looking through source control history to understand some code, but equally importantly, they won’t find it on its own and be unsure whether it’s still relevant. When it’s part of the git history, the history itself tells you whether those changes stuck around or were superseded. Checking the ori…
I came to the same conclusion. I wanted to write ADRs since the first time I read about them a few years back. Thinking more about it I concluded that commit messages are the right place to document this. You can find the commit for a line of code and you can just read git log.
If people tried both and have opinions please share. So far I am ok with commit messages even if they tend to be long.
Another thing. How do you people think ADRs compare to design docs? IMO design docs are for gathering feedback and ADRs are for documenting decided things, there is some overlap.
Re: Why Write ADRs
#16So 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.
>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.
Re: Why Write ADRs
#17yet another name for documentation nobody will write, but the manager will be able to say "solved the lack of documentation this quarter by implementing XYZ".
Re: Why Write ADRs
#18[deleted]
Re: Why Write ADRs
#19They could have included some nice examples from GitHub themselves in this blog article.
Re: Why Write ADRs
#20The basic idea is good, but isn’t a commit message the best place for this? That will ensure that people will find it when looking through source control history to understand some code, but equally importantly, they won’t find it on its own and be unsure whether it’s still relevant. When it’s part of the git history, the history itself tells you whether those changes stuck around or were superseded. Checking the ori…
I came to the same conclusion. I wanted to write ADRs since the first time I read about them a few years back. Thinking more about it I concluded that commit messages are the right place to document this. You can find the commit for a line of code and you can just read git log. If people tried both and have opinions please share. So far I am ok with commit messages even if they tend to be long. Another thing. How do…
I don't distinguish between the feedback gathering and the decision record. I collect feedback by integrating it into an ADR draft. Once the decision is made, the ADR is frozen and by construction includes the design documentation.