Package net.tangly.dev.adr

package net.tangly.dev.adr
Provides support to process architectural design records in an application. The project can define application wide design decisions. Each module can provide own specific architecture guidance.

The architecture design records are documented using asciidoc syntax. Used abbreviations are:

AD
architecture decision is relevant for the architecture and associated costs
ADL
architecture decision log defines a history of all architecture decisions
ADR
architecture decision record document a single architecture decision
AKM
architecture knowledge management to support team members during evolution of the product
ASR
architecturally-significant requirement constraining the chosen architectural solution

If you're considering using decision records with your team, then here's some advice that we've learned by working with many teams.

You have an opportunity to lead your teammates, by talking together about the "why", rather than mandating the "what". For example, decision records are a way for teams to think smarter and communicate better; decision records are not valuable if they're just an after-the-fact forced paperwork requirement.

Some teams much prefer the name "decisions" over the abbreviation "ADRs". When some teams use the directory name "decisions", then it's as if a light bulb turns on, and the team starts putting more information into the directory, such as vendor decisions, planning decisions, scheduling decisions, etc. All of these kinds of information can use the same template. We hypothesize that people learn faster with words ("decisions") over abbreviations ("ADRs"), and people are more motivated to write work-in-progress docs when the word "record" is removed, and also some developers and some managers dislike the word "architecture".

In theory, immutability is ideal. In practice, mutability has worked better for our teams. We insert the new info the existing ADR, with a date stamp, and a note that the info arrived after the decision. This kind of approach leads to a "living document" that we all can update. Typical updates are when we get information thanks to new teammates, or new offerings, or real-world results of our usages, or after-the-fact third-party changes such as vendor capabilities, pricing plans, license agreements, etc.