How to start using ADRs

To start using ADRs, talk with your teammates about these areas.

Decision identification:

• How urgent and how important is the AD?

• Does it have to be made now, or can it wait until more is known?

• Both personal and collective experience, as well as recognized design methods and practices, can assist with decision identification.

• Ideally maintain a decision todo list that complements the product todo list.

Decision making:

• A number of decision making techniques exist, both general ones and software architecture specific ones, for instance, dialogue mapping.

• Group decision making is an active research topic.

Decision enactment and enforcement:

• ADs are used in software design; hence they have to be communicated to, and accepted by, the stakeholders of the system that fund, develop, and operate it.

• Architecturally evident coding styles and code reviews that focus on architectural concerns and decisions are two related practices.

• ADs also have to be (re-)considered when modernizing a software system in software evolution.

Decision sharing (optional):

• Many ADs recur across projects.

• Hence, experiences with past decisions, both good and bad, can be valuable reusable assets when employing an explicit knowledge management strategy.

Decision documentation:

• Many templates and tools for decision capturing exist.

• See agile communities, e.g. M. Nygard’s ADRs.

• See traditional software engineering and architecture design processes, e.g. table layouts suggested by IBM UMF and by Tyree and Akerman from CapitalOne.

For more:

• The steps above are adopted from the Wikipedia entry on Architectural Decision