• Stars
    star
    11,128
  • Rank 2,905 (Top 0.06 %)
  • Language
  • Created over 7 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Architecture decision record (ADR) examples for software planning, IT leadership, and template documentation

Architecture decision record (ADR)

An architecture decision record (ADR) is a document that captures an important architecture decision made along with its context and consequences.

Contents:

Templates:

Examples:

What is an architecture decision record?

An architecture decision record (ADR) is a document that captures an important architectural decision made along with its context and consequences.

An architecture decision (AD) is a software design choice that addresses a significant requirement.

An architecture decision log (ADL) is the collection of all ADRs created and maintained for a particular project (or organization).

An architecturally-significant requirement (ASR) is a requirement that has a measurable effect on a software systemโ€™s architecture.

All these are within the topic of architecture knowledge management (AKM).

The goal of this document is to provide a fast overview of ADRs, how to create them, and where to look for more information.

Abbreviations:

  • AD: architecture decision

  • ADL: architecture decision log

  • ADR: architecture decision record

  • AKM: architecture knowledge management

  • ASR: architecturally-significant requirement

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.

  • Group decision making is an active research topic.

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.

Decision guidance:

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

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

How to start using ADRs with tools

You can start using ADRs with tools any way you want.

For example:

  • If you like using Google Drive and online editing, then you can create a Google Doc, or Google Sheet.

  • If you like use source code version control, such as git, then you can create a file for each ADR.

  • If you like using project planning tools, such as Atlassian Jira, then you can use the tool's planning tracker.

  • If you like using wikis, such as MediaWiki, then you can create an ADR wiki.

How to start using ADRs with git

If you like using git version control, then here is how we like to start using ADRs with git for a typical software project with source code.

Create a directory for ADR files:

$ mkdir adr

For each ADR, create a text file, such as database.txt:

$ vi database.txt

Write anything you want in the ADR. See the templates in this repository for ideas.

Commit the ADR to your git repo.

ADR file name conventions

If you choose to create your ADRs using typical text files, then you may want to come up with your own ADR file name convention.

We prefer to use a file name convention that has a specific format.

Examples:

  • choose-database.md

  • format-timestamps.md

  • manage-passwords.md

  • handle-exceptions.md

Our file name convention:

  • The name has a present tense imperative verb phrase. This helps readability and matches our commit message format.

  • The name uses lowercase and dashes (same as this repo). This is a balance of readability and system usability.

  • The extension is markdown. This can be useful for easy formatting.

Suggestions for writing good ADRs

Characteristics of a good ADR:

  • Rationale: Explain the reasons for doing the particular AD. This can include the context (see below), pros and cons of various potential choices, feature comparions, cost/benefit discussions, and more.

  • Specific: Each ADR should be about one AD, not multiple ADs.

  • Timestamps: Identify when each item in the ADR is written. This is especially important for aspects that may change over time, such as costs, schedules, scaling, and the like.

  • Immutable: Don't alter existing information in an ADR. Instead, amend the ADR by adding new information, or supersede the ADR by creating a new ADR.

Characteristics of a good "Context" section in an ADR:

  • Explain your organization's situation and business priorities.

  • Include rationale and considerations based on social and skills makeups of your teams.

  • Include pros and cons that are relevant, and describe them in terms that align with your needs and goals.

Characteristics of good "Consequences" section in an ADR:

  • Explain what follows from making the decision. This can include the effects, outcomes, outputs, follow ups, and more.

  • Include information about any subsequent ADRs. It's relatively common for one ADR to trigger the need for more ADRs, such as when one ADR makes a big overarching choice, which in turn creates needs for more smaller decisions.

  • Include any after-action review processes. It's typical for teams to review each ADR one month later, to compare the ADR information with what's happened in actual practice, in order to learn and grow.

A new ADR may take the place of a previous ADR:

  • When an AD is made that replaces or invalidates a previous ADR, then a new ADR should be created

ADR example templates

ADR example templates that we have collected on the net:

Teamwork advice

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 capabilties, pricing plans, license agreements, etc.

For more information

Introduction:

Templates:

In-depth:

Tools:

Company-Specific Guidance:

Examples:

See also:

  • REMAP (Representation and Maintenance of Process Knowledge)

  • DRL (Decision Representation Language)

  • IBIS (Issue-Based Information System)

  • QOC (Questions, Options, and Criteria)

  • IBMโ€™s e-Business Reference Architecture Framework

More Repositories

1

queueing-theory

Queueing theory: an introduction for software development
2,078
star
2

monorepo-vs-polyrepo

Monorepo vs. polyrepo: architecture for source code management (SCM) version control systems (VCS)
991
star
3

git-commit-message

Git commit message: how to write a great git commit message and commit template for version control
915
star
4

ways-of-working

Ways of Working (WoW) with team principles, values, tenets, ground rules, aspirations, norms, working agreements, shared expectations, and group understandings
619
star
5

objectives-and-key-results

Objectives and Key Results (OKR) examples for goals, tasks, plans, projects, and strategy.
344
star
6

pitch-deck

Pitch deck advice for startup founders who want to raise venture capital investment
285
star
7

demo-rust-axum

Demo of Rust and axum web framework with Tokio, Tower, Hyper, Serde
Rust
278
star
8

github-special-files-and-paths

GitHub special files and paths, such as README, LICENSE, .github, docs, dependabot, workflows.
192
star
9

stable-diffusion-image-prompt-gallery

Stable Diffusion: image prompt gallery of examples for various prompts
Shell
178
star
10

maturity-models

Maturity models for IT, Agile, DevOps, TOGAF, Six Sigma, P3M3, etc.
172
star
11

plantuml-examples

PlantUML eaxmples for UML, ERD, wireframes, mind maps, JSON, YAML, WBS, ASCII art, Gantt charts, C4 models, and more
168
star
12

git-commit-template

Git commit template for better commit messages
163
star
13

stable-diffusion-macos-install-help

Stable Diffusion: macOS install help with homebrew, python, anaconda, dream, etc.
130
star
14

key-performance-indicator

Key performance indicator (KPI) examples for metrics, measurements, objectives and key results (OKRs)
129
star
15

brewfile

Brewfile
Ruby
111
star
16

crucial-conversations

Crucial conversations: lessons from the worldwide bestseller book
95
star
17

decision-record

Decision record: how to initiate and complete decisions for teams, organizations, and systems
92
star
18

statement-of-work

Statement Of Work (SOW) example
67
star
19

demo-swift-excel-xlsx-reader-writer

Demo Swift Excel Xlsx Reader Writer
Swift
60
star
20

inclusive-language

Inclusive language
57
star
21

strategic-balanced-scorecard

Strategic Balanced Scorecard: planning business by using OKRs, KPIs, and initiatives
49
star
22

issues

Issues: feature requests, bug reports, customer complaints, security alerts, etc.
44
star
23

oblique-strategies

Oblique Strategies: ideas for creative lateral thinking
42
star
24

care-plan

Care plan: a free open source care plan template for caregivers to help with medical, financial, government, legal, and practical care.
41
star
25

startup-superset

Startup superset: summaries of key concepts, ideas, insights
40
star
26

functional-specifications-template

Functional specifications template
40
star
27

always-improving

Book summaries by "alwaysimproving" for business, productivity, life skills, etc.
35
star
28

milestones

Milestones ideas and examples for project management
32
star
29

software-development-methodologies

Software development methodologies: summaries of agile, scrum, DAD, SAFe, etc.
31
star
30

social-network-plan

Social network plan - goals, ideas, step, and tasks for a new site
30
star
31

company-culture

Company culture ideas from Amazon, Netflix, Harvard, Ultimate, etc.
28
star
32

versioning

Versioning: what it is, how to do it, comments and discussion
28
star
33

leadership

Leadership and management ideas
27
star
34

spade-decision-framework

SPADE decision framework: Setting, People, Alternatives, Decide, Explain
27
star
35

system-quality-attributes

Cross-Functional Requirements a.k.a. Quality Attributes
26
star
36

ooda-loop

OODA loop: notes on John Boyd, strategy, tactics, planning, and paradigms
25
star
37

powerful-questions

Powerful questions - catalyzing insight, innovation, action
25
star
38

business-model-canvas

Business model canvas for value propositions, customer relationships, partner collaborations, etc.
25
star
39

thought-leadership-writing

Thought leadership writing tips for content creators, bloggers, authors, and editors
24
star
40

awesome-developing

Awesome developing: ideas for how to create better software code and collaboration
24
star
41

value-stream-mapping

Value Stream Mapping (VSM) tutorial (work in progress)
24
star
42

big-five-personality-traits

Big Five personality traits: domains, aspects, facets
22
star
43

source-code-management

Source code management โ†’ notes and ideas โ†’ mono-repos, trunk-based-development, etc.
21
star
44

key-risk-indicator

Key risk indicator (KRI) for risk management and business strategy
20
star
45

wordbooks

Demo wordbooks for business, projects, industries, software, consulting, and more
Lua
20
star
46

code-of-conduct-guidelines

Code of Conduct Guidelines
Shell
19
star
47

git-branch-name

Git branch name ideas, naming conventions, and how to use git branch edit description
19
star
48

git-workflow-help

Git flow help: research on Git flow, GitHub flow, GitLab flow, etc.
18
star
49

demo-tailwind-css

Demo Tailwind CSS along with Gulp and PostCSS
JavaScript
18
star
50

functional-specifications-tutorial

Functional specifications tutorial
17
star
51

sha256-sentence

SHA256 sentence: discover a SHA256 checksum that matches a sentence's description of hex digit words.
Rust
17
star
52

team-focus

TEAM FOCUS concepts by Paul N. Friga in McKinsey Engagement.
17
star
53

stakeholder-analysis

Stakeholder analysis for business project management
HTML
17
star
54

smart-criteria

SMART criteria for goals, objectives, plans, etc.
16
star
55

interviewing

Interviewing ideas for hiring managers, job seekers, and recruiting candidates
16
star
56

vision_mission_statements

Vision statements and mission statements by many companies and organizations
16
star
57

goals-ideas-steps-tasks

Goals, Ideas, Steps, Tasks: GIST Planning
14
star
58

icebreaker-questions

Icebreaker questions to help people, groups, teams, meetings, and such
14
star
59

coordinated-disclosure

Coordinated disclosure for security discoveries, bug reports, etc.
13
star
60

outputs-vs-outcomes

Outputs vs. outcomes: what's the different and why does it matter?
12
star
61

discovery-assessment

Discovery assessment for project management
12
star
62

critical-success-factor

Critical Success Factor (CSF) tutorial
12
star
63

software-operations-items

Software operations items
12
star
64

demo-rust-cargo-tdd

Demo of Rust and Cargo for TDD (test driven development)
Rust
11
star
65

agile-assessment

Agile assessment exercise ideas
11
star
66

metrics

Metrics
10
star
67

responsibility-assignment-matrix

Responsibility assignment matrix (RAM) a.k.a. linear responsibility chart (LRC)
10
star
68

social-value-orientation

Social value orientation (SVO) notes for pro-social pro-self concepts
10
star
69

demo-elixir-phoenix

Demonstration of Elixir language and Phoenix framework
Elixir
10
star
70

pgp-gpg-help

Pretty Good Privacy (PGP) GNU Privacy Guard (GPG) help for encryption
9
star
71

causal-analysis-based-on-system-theory

Causal Analysis based on System Theory (CAST)
9
star
72

demo-job-descriptions

Demo job descriptions
9
star
73

demo-terraform-aws

Demo of Terraform by Hasicorp for AWS
HCL
9
star
74

lean-business-lists

Lean business lists
9
star
75

issue-postmortem-template

Issue postmortem template for incident response documentation
8
star
76

net-promoter-score

Net Promoter Score (NPS) introduction and recommendations
8
star
77

initiatives-and-experiments

Initiatives and experiments
8
star
78

demo-rust-cursive

Demo Rust Cursive crate for terminal user interface (TUI)
Rust
8
star
79

demo-swift-rest

Demo Swift REST
HTML
8
star
80

git-hooks

Git hooks
Shell
7
star
81

demo-devops

Demo devops
7
star
82

adkar-change-management-model

ADKAR change management model: awareness, desire, knowledge, ability, reinforcement
7
star
83

demo-optaplanner

Demo OptaPlanner constraint solver
Java
6
star
84

intent-plan

Intent plan for mision, state, sequence, decisions, antigoals, constraints, expressives
6
star
85

demo-rust-rocket

Demo of Rust Rocket web application framework
Rust
6
star
86

task-life-cycle

Task life cycle (TLC)
5
star
87

feedback-request-template

Feedback request template
5
star
88

first-aid-kit

First Aid Kit
5
star
89

inspiring-people

Inspiring people: one hundred living people with short bios thanks to Wikipedia
5
star
90

principles

Principles: summaries of ethical prinicples, leadership principles, teamwork principles, ui/ux design principles, software programming principles, etc.
5
star
91

demo-aws-ses-smtp

Demo of Amazon Web Services (AWS) Simple Email Service (SES) Simple Mail Transfer Protocol (SMTP)
4
star
92

aberystwyth-wales-book

Aberystwth Wales Book - Photos of the Town
Shell
4
star
93

safety-philosophy

Safety philosopy: example principles for an organization and management
4
star
94

demo-shopping-cart-exercise-with-ruby

Shopping cart exercise with Ruby: how to program a shop, cart, till, checkout, etc. with TDD
Ruby
4
star
95

demo-gulp

Demo gulpfile.js using Gulp, PostCSS, Tailwind CSS, Pino, unfold, and more
JavaScript
4
star
96

git-troubleshooting

Git troubleshooting
4
star
97

demo-svelte-hello-world

Demo Svelte JavaScript framework "hello world" app
JavaScript
4
star
98

demo-ansible

Demo Ansible configuration tool for install, update, users, groups, etc.
4
star
99

quad-chart

Quad chart: a rapid project planning summary guide
4
star
100

adventure-gear

Adventure gear for traveling, backpacking, camping, and more
4
star