First ADR should always be about why we introduce ADRs in a project!

[christian-weiss]

If you introduce ADRs into a project (or organisation), then the decision to introduce ADRs should be recorded as an ADR.

This ADR context should explain:

• WHY documenation of architectural decisions is required,
• WHY introducing ADRs it is a architectural decision and not a normal decision
• WHY the ADR approach is best for your project (maybe what other approaches you had considered)

To collect some examples as inspiration to others: Please attach to this github issue your ADR, that introduces ADRs to your project. (This may help others to put arguments when introducing ADRs) ;-)

Consequences - e.g.:

• enables the "future me" to recall the old context correctly when reviewing this decision e.g. 12 month in the future (when i hopefully will have gained more knowledge)
• enables your team mates to "review", "accept" and "operate" on this decision (better team knowledge)
• enables team mates to challenge decisions today or in the future (by being able to detect changes in old and latest context)
• enables future team mates to join the project more easyer
• enables to reduce the communication overhead involved when decision is not written down (1:1-chats for knowledge-transfer; imaging team sizes of >10)
• ...your argument here...

Or do you think that ADR is not a AD at all?

[mgan59]

Agree, it is important to indicate in the first ADR what format is being adopted 👍🏻

I use the Homebrew ADR CLI tool (created by Nat Pryce) which by default supports Michael Nygards ADR format. When you run adr init in a new project it creates the default ADR-0001

---

# 1. Record architecture decisions

Date: 2019-03-19

## Status

Accepted

## Context

We need to record the architectural decisions made on this project.

## Decision

We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).

## Consequences

See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).

[sunnybharne]

This was very helpful, Until now I though of ADR as a wiki document. Turns out that it does not have to be a fancy application which can do fancy stuff. .md files works just fine.