Architectural Decisions Revisited

Back in 2016 I wrote about Architectural Decision Records (ADRs) in my post "Why did we do it that way?". These are lightweight documents stored in a software project codebase along with the code that document point-in-time decisions about the architecture for future reference. Since then I have had projects that used them and others that didn't in lieu of other ways of documenting decisions.

I recently ran across a great post from Kelvin Meeks on ADRs that lists a lot of great information and resources. I also like the project he links to as an example containing a good number of records that is still an active project at the time I am writing this.

In fact, since my original post a Github Organization for ADRs has been created that includes articles, resources, guidance, and tooling for using these records.

If you have ever lamented not capturing why a choice was made or want to improve how decisions are documented by having them live right along with the project(s) they describe, see if ADRs might be a good fit for your situation.

Published: 2024-03-23

Tags: design

Decomposing Work Items

One of the early conversations I have with most teams I work with is about decomposition. There is often just a high level of variation in size, complexity, and other aspects of work in progress. This makes it hard to project when things will complete, when we will be able to get to new things, and how much of in-progress work was essential vs. deferrable.

Continue reading

Published: 2019-02-16

Why did we do it that way?

Have you ever joined a project and not soon after questioned why things are the way they are? Why was this language (or framework) chosen over another? Why do we (or don't we) organize things into microservices? Why are errors handled the way they are? What drove the choice of database, or API design, or external service?

These questions always come up. It's a natural part of understanding a new work environment. It happens every time. And I don't like being in the position of saying "I'm not sure why this was done/used" in the course of fixing something or implementing something new.

Continue reading

Published: 2016-10-27

Tags: design

Archive