docs: Add Key Design Decisions documentation #128
Conversation
jonnyandrew
force-pushed
the
jonny/adrs
branch
from
ebed508 to
cbe64a6
Compare
jonnyandrew
changed the base branch from
main
to
jonny/update-pipelines-413b2f4
jonnyandrew
force-pushed
the
jonny/adrs
branch
from
cbe64a6 to
1269d8a
Compare
| @@ -0,0 +1,47 @@ | |||
| # Storing Architectural Design Records (ADRs) | |||
There was a problem hiding this comment.
I'm just wondering about the thought process about doing this as an ADR / decision format, rather than regular documentation of things we've built.
I think this could make it harder to find information because ADR format is designed more as an audit trail where things change over time, and decisions get revoked by more recent decisions, rather than necessarily amended.
There was a problem hiding this comment.
Also, is this repository the right place to hold that?
If decisions are wider than this codebase, where would they live?
- Here or in a different repository?
- Would we duplicate decisions across repositories?
We do also already have a process (TDF) for cross-Pod decisions, where things live on Confluence.
There was a problem hiding this comment.
I'd be interested in @AdamHigginsonGDS's take on this one too.
There was a problem hiding this comment.
Hey - yes I'm keen we don't end up with a proliferation of adr-like tech docs throughout the program, I already think discoverability is a real challenge for people (e.g. we have ADRs/RFCs/tech manual/confluence/jira... you get the picture).
If we'd like to keep a record of tech decisions, can we use the Tech Design process (https://govukverify.atlassian.net/wiki/spaces/DCMAW/pages/3436183661/What+Is+TDF), and then link from the README any decisions?
There was a problem hiding this comment.
ADR / decision format, rather than regular documentation of things we've built.
@obinns-dd I think both are valuable, but the need for ADRs is to record the reasoning why a decison was made and why the architecture exists. I'm keen not to lose the value that we've created through meetings and slack threads, that we could share.
I think regular documentation of the project architecture would also be useful to create but it doesn't necessarily capture all the context other teams might need to learn from and make a case for introducing to their own projects.
There was a problem hiding this comment.
By the way, these are good questions that this first ADR should definitely address! I'll try to incorporate all of this in a clearer way.
There was a problem hiding this comment.
@AdamHigginsonGDS - in case any confusion, your messages hadn't arrived when I wrote my earlier replies to @obinns-dd's messages
There was a problem hiding this comment.
To give a concrete example:
We recently had a discussion around the architecture of our analytics within this repository. We identified that we're tightly coupled to a problematic analytics framework, discussed several options for improvement and the trade-offs, and ultimately settled on accepting the coupling.
Here's the comment thread: #92 (comment)
Now this is definitely not something I'd bring to TDF because the scope is very much limited to this repository. But it could still be valuable to distil into an ADR for future developers.
Does that give you an idea of where I'm coming from? Perhaps I can include a few examples of what is and isn't appropriate and link to TDF so that we explictly cover cross-pod/cross-programme knowledge sharing as an alternative?
There was a problem hiding this comment.
I've updated the ADR to hopefully address your concerns:
- Update the name of this documentation from 'ADR' to 'local ADR'
- Highlight Technical Design Forum as an alternative and compare the different scopes and use cases
- Link to documentation about Technical Design Forum
There was a problem hiding this comment.
After talking we've agreed to rename from 'ADR' to Key Design Decision (KDD) to avoid giving the impression that this documentation will have a process as thorough as the ADR process from govuk-one-login/architecture.
jonnyandrew
changed the title
jonnyandrew
changed the title
jonnyandrew
force-pushed
the
jonny/adrs
branch
from
fdf8f96 to
e730a0b
Compare
jonnyandrew
force-pushed
the
jonny/adrs
branch
from
e730a0b to
dbbc76f
Compare
|
Changes
Add documentation about Key Design Decisions (KDD).
Evidence of the change
Checklist
Before publishing a pull request
draftpull request if it's not ready for review.Before the CODEOWNERS review the pull request