[HN Gopher] Why Write ADRs
___________________________________________________________________
Why Write ADRs
Author : imsky
Score : 80 points
Date : 2020-08-13 18:32 UTC (4 hours ago)
(HTM) web link (github.blog)
(TXT) w3m dump (github.blog)
| BillSaysThis wrote:
| Shout out to my pal Joel, who was in this space for awhile
| already!
| https://github.com/joelparkerhenderson/architecture_decision...
| linux2647 wrote:
| I started a new job about six months ago and the engineering org
| writes ADRs. As a new hire, this was incredibly useful to
| understand some of the hows and whys of past decisions that would
| normally take me years to discover or understand.
| alsdkfjkqjwer wrote:
| yet 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".
| jph wrote:
| Architectural decision record repo:
| github.com/joelparkerhenderson/architecture_decision_record/
|
| Pull requests welcome, such as if you have an ADR template, or
| sample, or link.
| wdb wrote:
| They could have included some nice examples from GitHub
| themselves in this blog article.
| cosmic_quanta wrote:
| I had never heard of ADRs, but now I see that I've been putting
| some of the information in comments or module-level docs. I'll
| definitely look into the linked examples!
| Inversechi wrote:
| A community that I've seen doing this pretty well is the Home
| Assistant community. You might wanna check their examples out.
|
| https://github.com/home-assistant/architecture
| sbuttgereit wrote:
| 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.
|
| http://pages.cs.wisc.edu/~remzi/Naur.pdf
| rabidrat wrote:
| These 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 your story points
| done for this sprint and meet your OKRs for this quarter.
| DyslexicAtheist wrote:
| 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.
| aplummer wrote:
| > But make sure you also get your story points done for this
| sprint and meet your OKRs for this quarter.
|
| The problem here is the points aren't measuring quality, they
| are measuring a type of velocity that doesn't take into account
| quality if you aren't getting points for that work.
|
| Read: PMs often drive a timeline that accepts engineering risk,
| but not responsibility for that decision when it doesn't work.
| iainmerrick wrote:
| The 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 original post to make sure I'm not just repeating
| it, I don't think I am -- it links to
| https://github.com/joelparkerhenderson/architecture_decision...
| which proposes a whole bunch of acronyms (ADL, ADR, AKS, ASR) but
| doesn't offer an opinion on _where_ they should be stored! This
| is bureaucracy for bureaucracy's sake, missing the wood for the
| trees.
|
| _Edit to add:_ I'm not quite right, it does offer an opinion; it
| suggests text files in an "adr" directory. For the reasons
| outlined above I think this is both more and less than you need.
| (Maybe there should be an ADR for the location of the ADR
| directory...?)
|
| TL;DR: we don't need a whole new set of complex workflows for
| this, we just need good commit messages.
| ralphael wrote:
| so what would the experience be for someone new joining the
| project, particular if you have many repositories? having to
| search across numerous repositories? In practice I've found
| this (source control commit messages as ADR's) doesn't work.
| Unless I have mistaken what you have said? I just keep a
| repository for ADR's, which can then be published to a wiki or
| else where.
| iainmerrick wrote:
| In that situation, I think the best layout is:
|
| - your centralised wiki lists all the repositories and
| explains what they're for;
|
| - each repository has a detailed commit history, allowing you
| to understand the thinking behind each line of code.
|
| _Edit to add:_ you can search across multiple repos with
| Github's "search in organization" feature, and it actually
| works very well. I usually find that much more useful than
| searching through a wiki that's separate from the code
| (although maybe I just haven't ever seen a wiki that was
| sufficiently well organized?)
| codesuki wrote:
| 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.
| qznc wrote:
| 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.
| jayd16 wrote:
| 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.
| qznc wrote:
| 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.
| coldtea wrote:
| > _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.
___________________________________________________________________
(page generated 2020-08-13 23:00 UTC)