Skip to content

Commit

Permalink
Add how-to-start-using-adrs
Browse files Browse the repository at this point in the history
  • Loading branch information
joelparkerhenderson committed Nov 7, 2023
1 parent c99aab6 commit 7be7874
Show file tree
Hide file tree
Showing 3 changed files with 48 additions and 0 deletions.
1 change: 1 addition & 0 deletions locales/en/doc/how-to-start-using-adrs/.locale-peer-id
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
8196518140224596af99a46d512feba3
1 change: 1 addition & 0 deletions locales/en/doc/how-to-start-using-adrs/README.md
46 changes: 46 additions & 0 deletions locales/en/doc/how-to-start-using-adrs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# 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 exists, 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](https://en.wikipedia.org/wiki/Architectural_decision)

0 comments on commit 7be7874

Please sign in to comment.