(highlight:: Agile methods are not opposed to documentation, only to valueless
documentation. Documents that assist the team itself can have value,
but only if they are kept up to date. Large documents are never kept
up to date. Small, modular documents have at least a chance at being
updated.)
- No location available
-

(highlight:: Nobody ever reads large documents, either. Most developers have been
on at least one project where the specification document was larger
(in bytes) than the total source code size. Those documents are too
large to open, read, or update. Bite sized pieces are easier for for
all stakeholders to consume.)
- No location available
-
- [note::"Bite-sized pieces are easier for all stakeholders to consume" - this is why multi-layered diagramming (e.g. C4 model, Ilograph) is ideal.]

(highlight:: If the project accumulates too many
decisions accepted without understanding, then the development
team becomes afraid to change anything and the project collapses
under its own weight.)
- No location available
-

(highlight:: Title These documents have names that are short noun phrases. For
example, "ADR 1: Deployment on Ruby on Rails 3.0.10" or "ADR 9: LDAP
for Multitenant Integration"
Context This section describes the forces at play, including
technological, political, social, and project local. These forces are
probably in tension, and should be called out as such. The language in
this section is value-neutral. It is simply describing facts.
Decision This section describes our response to these forces. It
is stated in full sentences, with active voice. "We will …"
Status A decision may be "proposed" if the project stakeholders
haven't agreed with it yet, or "accepted" once it is agreed. If a
later ADR changes or reverses a decision, it may be marked as
"deprecated" or "superseded" with a reference to its replacement.
Consequences This section describes the resulting context, after
applying the decision. All consequences should be listed here, not
just the "positive" ones. A particular decision may have positive,
negative, and neutral consequences, but all of them affect the team
and project in the future.
The whole document should be one or two pages long. We will write each
ADR as if it is a conversation with a future developer. This requires
good writing style, with full sentences organized into
paragraphs. Bullets are acceptable only for visual style, not as an
excuse for writing sentence fragments. (Bullets kill people, even
PowerPoint bullets.))
- No location available
-
- [note::ADR format:

• Title
• Context
• Decision
• Status
• Consequences (positive AND negative)
  Written as if in conversation with a future developer.]

(highlight:: Agile methods are not opposed to documentation, only to valueless
documentation. Documents that assist the team itself can have value,
but only if they are kept up to date. Large documents are never kept
up to date. Small, modular documents have at least a chance at being
updated.)
- No location available
-

(highlight:: Nobody ever reads large documents, either. Most developers have been
on at least one project where the specification document was larger
(in bytes) than the total source code size. Those documents are too
large to open, read, or update. Bite sized pieces are easier for for
all stakeholders to consume.)
- No location available
-
- [note::"Bite-sized pieces are easier for all stakeholders to consume" - this is why multi-layered diagramming (e.g. C4 model, Ilograph) is ideal.]

(highlight:: If the project accumulates too many
decisions accepted without understanding, then the development
team becomes afraid to change anything and the project collapses
under its own weight.)
- No location available
-

(highlight:: Title These documents have names that are short noun phrases. For
example, "ADR 1: Deployment on Ruby on Rails 3.0.10" or "ADR 9: LDAP
for Multitenant Integration"
Context This section describes the forces at play, including
technological, political, social, and project local. These forces are
probably in tension, and should be called out as such. The language in
this section is value-neutral. It is simply describing facts.
Decision This section describes our response to these forces. It
is stated in full sentences, with active voice. "We will …"
Status A decision may be "proposed" if the project stakeholders
haven't agreed with it yet, or "accepted" once it is agreed. If a
later ADR changes or reverses a decision, it may be marked as
"deprecated" or "superseded" with a reference to its replacement.
Consequences This section describes the resulting context, after
applying the decision. All consequences should be listed here, not
just the "positive" ones. A particular decision may have positive,
negative, and neutral consequences, but all of them affect the team
and project in the future.
The whole document should be one or two pages long. We will write each
ADR as if it is a conversation with a future developer. This requires
good writing style, with full sentences organized into
paragraphs. Bullets are acceptable only for visual style, not as an
excuse for writing sentence fragments. (Bullets kill people, even
PowerPoint bullets.))
- No location available
-
- [note::ADR format:

• Title
• Context
• Decision
• Status
• Consequences (positive AND negative)
  Written as if in conversation with a future developer.]