Document Your Architecture Decisions with ADRs

https://newsletter.fractionalarchitect.io/p/12-document-it-architecture-decision

10 12 2 years ago

newsletter.fractionalarchitect.io

taylodl• 2 years ago

And track your ADRs in your preferred SCM system.

troyvit• 2 years ago

I have two questions about this. First, what does the first entry look like? Most people don't have ADR started, so these decisions will come on top of an existing infrastructure. What's the first doc look like that holds that info?

Second, I wonder if it would also be good to include decisions NOT made or choices to NOT do a thing. ie.

Title: Set up separate S3-compatible instance for back-up image storage

Date when it occurred: 2024-07-16

Problem description: If our image server became inaccessible our site wouldn't have images.

Decision: Nah too expensive

Consequences of the decision: Really amazing ascii art from our photographers after [pick your AWS region] went down

jacknews• 2 years ago

Not the OP, but the 'decision' section is the place to describe trade-offs and rejected solutions, I think?

To start a new project, an overall 'design' or 'requirements' section. I'm not sure how you'd deal with an existing large code-base.

meaboutsoftware5• 2 years ago

First answer: if you don't have any ADR yet, start with documenting the first decision that comes - don't go back in time to record 2 YO decisions.

Second: I described it as "Considered alternatives". There are 2 schools. One that puts it in "Decision" and the second one that puts it in "Considered alternatives " :)

I wouldn't document decisions that were not made as a separate ADR - it would be a mess after some time.

adrianmsmith• 2 years ago

Anything that relies on files having names like 0001-foo isn't going to work nicely if you are using Git, merge/pull requests and branches, with developers working on features independently.

I'm going to see that 0024 was the last file and add a 0025, and you while working on your feature will see the same and add a file with the same number. This will have to be noticed and resolved via renaming files during rebase and merge, etc., which is pointless busywork and easy to get wrong.

Also, I don't see why these need to be ordered sequentially at all. Surely e.g. a file like "architecture.md" or individual files like "database.md" would be better? If you change the code and that involves changing the architecture, you also update the document. You are free to include information such as why you made the change, alternatives and why they were not chosen etc., just as with this 0001-foo.md.

If you are joining a team and want to learn about the database, it's much easier to open "database.md" and find the current state, vs. reading through 0001 through 0245 where 0009 introduces why MySQL is used, 0051 explains why PostgreSQL is now being used instead of MySQL, 0121 introduces some changes, and so on. Having individual files like that is like reading Git diffs from start to finish where what you really want is the current state.

meaboutsoftware5• 2 years ago

Each architecture decision record should be added after the decision of the entire team. Then one folk can be assigned to add the ADR to the repo. It will work fine even if you do feature branches (battle-tested but you need to keep you branches short). In case of trunk-based development, there is no problem multiple feature branches.

The idea of ADR is to be immutable. Having multiple, ordered ADRs that touch e.g. the database works similarly to event sourcing - you have the entire history of all changes that were done within the context.

If you want to keep the entire history with changes in a single file called "database", then that's fine but the most important thing is to keep the history of decisions.

Having a single file with only the last decision is not the optimal idea as you lose the entire history.

librasteve• 2 years ago

not sure i understand the benefit of having files in a dir vs. using Issue templates and labels named eg. “Architecture Design”. then you get auto numbers, PRs that autolink back to the issue and a discussion thread

meaboutsoftware5• 2 years ago

In case of monorepo where there are several independent deployment units, separating it via dir is quite simple solution. Additionally, if you move the code to some other provider, you move it together with the code (what is not guaranteed with e.g. GH issues).

However, I don't say NO. It all depends on context, if you decide to use issues - go ahead. I am a fan of pragmatism - do what you need in your context, don't blindly follow the rules

octokatt2• 2 years ago

I know folk are ripping down this straw-man, which is reasonable, but what are better best practices?

I'll start, I'd rather have YYMMDD_xx_title-words.md, where xx are the principal engineer's initials. It'll handle the merge/pull issue, and also show at a glance who was making architectural decisions (and if they were making too many at once), though I would love to hear how something like this has blown up in the past.

meaboutsoftware5• 2 years ago

YYMMDD is also a cool idea! I used it in one of previous projects.

What I don't like in your proposal are initials - since 2020 I worked in the environments where all folks were invited in making architectural decisions (that's the way I always try to push as an architect), therefore it would make no sense to add any initials :)

octokatt2• 2 years ago

That's entirely fair, and precisely why I posted the framework. Thank you!

I guess what I'm solving for is trying to tag a specific person or group with why a decision got made, which... if there was an easy way to do that, politics would be a lot cleaner. Removing that, and just adding many-to-one tags for authors in-document, seems like it'll get to most of the desired requirement.

Document Your Architecture Decisions with ADRs

Related Stories