Architectural decision records answer “why” questions about designs and make tacit knowledge explicit. Many architectural decisions are made during development iterations because they have a close connection to the code. It is challenging to come up with task-specific decision capturing practices and supporting tools that are not perceived as time wasters; context switches and media breaks that harm the productivity of coding architects and developers involved in the decision making have to be avoided. To integrate existing architect-centric approaches into the developer toolchain, this paper presents a Markdown-based decision capturing template that we derived from previous work to enhance an existing decision capturing tool for developers. Our early validation results in the context of an open source project suggest that format and tool promise to contribute to an integrated decision capturing practice, with further enhancements being required. Tool and template are available in public GitHub repositories.
Source code needs to be documented. This typically leads to comments in code and to
external documents. Well-written classes and methods, which have expressive names
and understandable branches [
How to seamlessly integrate architectural decision making into developer tool landscapes — so that decision rationale can be collected under high coding velocity?
To describe how we propose to overcome this problem, we first provide some background and related work (Sect. 2). We then introduce the Markdown Architectural Decision Records (MADR) format as the conceptual contribution of this paper (Sect. 3). Next, we present a tool implementation for MADR integration that makes our conceptual solution available to practitioners and validates the novel format (Sect. 4). We have further validated the MADR format and tooling in an action research (Sect. 5). A discussion on the findings of MADR follows in Sect. 6. Finally, we conclude the paper (Sect. 7). 2
A large body of research work on capturing architectural decisions exists; the state of the
art is for instance surveyed by Alexeeva et al. [
More recently, templates, practices, and tools specifically targeting coding architects
and agile developers, who make certain architectural decisions and contribute to others,
have been proposed. Seven diferent formats, including comprehensive and lean ones,
are compared by Zimmermann et al. [
General best practice recommendations for decision documentation are presented by
Zdun et al. [
In the context of <use case/user story u>,
facing <concern c>
we decided for <option o>
and neglected <other options>,
to achieve <system qualities/desired consequences>,
accepting <downside / undesired consequences>,
because <additional rationale>.
rationale (Fig. 1). As a structured text format, Y-Statements can be put in external
documentation, in code comments [
An example of such a Y-statement is: “In the context of the Web shop service, facing
the need to keep user session data consistent and current across shop instances, we
decided for the Database Session State pattern [
A rather popular4 practitioner’s tool isadr-tools5. It uses the format by Nygard [
To keep the architectural decisions close to common developer tools and artifacts, we propose to 1) use Markdown as decision capturing syntax (with a proposed format derived from Y-Statements) and 2) place the decisions in the folder docs/adr of code projects that are version-controlled.
Markdown is a text format, which enables common version control systems such as git to be used. This makes difing within the IDE possible. Our decision to use Markdown as markup language (instead of other markup languages) is supported by the following rationale: 1) it eases writing, 2) Markdown is the markup language for comments by users within GitHub (such as in gists, issues, or pull requests), and 3) already available rendering tools can be leveraged.
We call the new format Markdown Architectural Decision Records (MADR). Some
early adopters of the Y-Statement syntax had commented that the sentences can get really
long and are therefore hard to read for inexperienced readerships. As Markdown is a
structured text format in which headings can mark sections, we decided to deviate from
the pure Y-format and transferred it into a section-oriented one (similar to the successful
approach of the adr-tools outlined in Sect. 2). The starting point was the “Decision
Capture Template” [
We indicate the backward mapping to the Y-format when describing the new template below (in parenthesis).
Figure 2 shows the format of MADR. Each record takes a title (line 1) followed by the user story (line 3). The user story is made optional because its content further elaborates on the mandatory context (from Y-Statement syntax) and problem statement (line 5). More information on the context such as forces or decision drivers (Y-Statement’s concerns and aims) can be appended (line 6). The considered alternatives (including the chosen and the neglected ones; Y-Statement) are listed as items (lines 8 to 11). The chosen alternative includes a justification (Y-Statement’s “to achieve” rationale) and optionally consequences (Y-Statement’s “accepting that” downsides). Follow-up decisions are are also listed as items (lines 13 to 19). If a longer pro/con evaluation of the alternatives makes sense, each option can be listed as a separate heading followed by an itemized list of pros and cons. In summary, all aspects of a Y-Statement are covered in the template, even though the consequences are left optional.
Note that MADR does not restrict the Markdown syntax. Thus, it is possible to include images, ASCII art, and PlantUML6.
The folder docs/adr was chosen to enable rendering in GitHub pages. Since 2016,
GitHub pages allows for rendering a homepage out of the docs folder [
To support MADR we extended adr-tools (made available at https://github.com/ adr/adr-tools) and created adr-log (made available as npm package at https://www. npmjs.com/package/adr-log).
The original adr-tools support arbitrary formats when creating new architectural decisions by providing an appropriate template.md file. New ADRs are put in the format nnnn - title-lowercased-with-dashes.md in the directory, where nnnn is a number starting from 0001. Besides basic creation functionality, adr-tools allows for linking ADRs. For instance, a new ADR can supersede an existing ADR. For that the status of an ADR is tracked under a new heading “Status”. In MADR, we record the status and the status changes in a table with the columns “Date” and “Status”. We extended adr-tools to support the command adr new docs/adr madr, where docs/adr is the directory where architectural decisions are put and madr denotes that MADR should be used as template format. At each call of adr new TITLE, MADR is used as template instead of Nygard’s template. Furthermore, we are working on supporting the status table in the beginning so that it is 1) created when an ADR is superseded by another ADR (e.g., adr -s 1 Use SQL Database, tells adr-tools to add a note at ADR-0001 that it is superseded) and 2) amended when there is a new link to an ADR (e.g., adr -l "1:Amends:Amended by" Use PosgreSQL, tells adr-tools that ADR-0001 is amended by the newly created ADR).
An index of existing architectural decision records is a welcome feature to gain an overview of the decision making status and be able to navigate the log eficiently. The existing adr-tools already ofers the command adr generate toc. This, however, generates a completely new file and does not allow to add arbitrary text before or after the toc. For the generation of the table of contents of one markdown file, the tool markdown-toc8 inserts the TOC after the token <!-- toc -->. Inspired by that idea, we implemented adr-log, which places the list of all ADRs after the placeholder <!-- adrlog -->. We chose the name “log” instead of “toc” to be consistent with the database terminology, where a set of records forms a log. 8 https://www.npmjs.com/package/markdown-toc 5
We validated MADR and tooling in action research [
In action research, the researcher joins a project and influences it actively, for instance as coach, pacemaker, or technical reviewer9. Applying action research allowed us to experience the practical applicability of our concepts ourselves and to interact with and learn from other users while they used MADR. We followed a very basic study protocol of 1) define validation goals and approach, 2a) present MADR and adr-tools to the project team and create a first MADR record ourselves (lead by example), 2b) monitor usage and remind project participants, e.g. in sprint planning meetings and retrospectives, 2c) give feedback to project participants and ofer coaching, and finally 3) collect data and seek suggestions for improvements from project participants.
A total of 16 MADR records were created.10 Eight of these fully filled out the template, and eight used a shortened form without the explicit section “Pros and Cons of the Alternatives”. Two of the short forms additionally include details of the solution. When working with code, it was easy to document the decision along with the code. A single file had to be copied and renamed (or adr new TITLE invoked). Then, one could start with writing down the context, options, chosen option, and the pros and cons.
Seasoned professionals did not have issues to fill out the template and even came up
with their own. Inexperienced students were able to document their decisions ranging
from supported writing to independent writing. A major issue for them was to understand
how to replace the placeholders in markdown. For instance, in ADR-000511, the options
listed there did neither have ids nor short titles. The chosen option was referred to as
“Option D”, but there was no explicit option D — only a fourth unnamed option. Some
students also reported that they were afraid to be criticized for options not considered.
Since MADR makes it explicit which options a solution was chosen from, it is easy to
detect if an important option was missed. On the positive side, this leads to a teaching
efect and allows supervisors to get to know which knowledge the students lack at a
certain educational level. On the one hand, it was agreed, that is dificult to create an ADR
if the technology itself is new. On the other hand, it was also agreed that is necessary to
document decisions after one has enough knowledge (e.g., after experimenting longer
with diferent options) to make it feasible for others to understand the decisions taken.
This is in line with Parnas’s view on a rational software process [
In summary, the users reported that the MADR template and tools helped them to be clear about the available options and to choose the best fitting one based on arguments. The template was filled during the discussions and helped to refine the pros and cons of alternatives. 9 This is diferent from exposing selected research results to users and merely observing them (this would be done in a controlled experiment). 10 https://github.com/eclipse/winery/tree/d84b9d7b6c9828fd20bc6b1e2fcc0cf3653c3d43/ docs/adr 11 https://github.com/eclipse/winery/blob/d84b9d7b6c9828fd20bc6b1e2fcc0cf3653c3d43/ docs/adr/0005-XML-editor-does-not-enforce-validation.md 6
Feedback from reviews and workshop raised some concerns whether placing ADRs in a single folder really scales: a complex system may consist of multiple microservices, and each microservice can itself be structured in diferent modules even written in diferent languages. Thus, the granularity of the decisions is diferent. Two possible solutions are: A) adding a category to each ADR and ofer filtering. B) putting each ADR close to the source code where the decision is taken, e.g., src/doc/adr for a Java project.
A developer began to add longer explanations of code howtos to the ADR. The reasoning was that this code howto is very related to the ADR and that there is one place where the decision and the coding consequences can be found. Thus, an interesting question requiring further investigation and discussion would be whether close-to-code (M)ADR documentation leads to an increased use of documentation (in comparison to external documentation).
The presented version 1.0.0 of MADR uses slightly diferent terms than the
YStatements (Sect. 3). We plan to refactor future versions of MADR12 to be even closer to
the terms of Y-Statements as these are proven in industry projects and have been gaining
momentum recently [
In large projects, it is common to create a project management issue for each change. In MADR, the link to an issue is optional to enable application in small projects. These two diferent settings call for MADR profiles . For instance, one such profile could enforce the link to the ticket/issue number (pointing to an entry in task management system) and make the section “pros and cons of the alternatives” mandatory. 7
This paper presented Markdown Architectural Decision (MADR) records, a decision capturing template derived from earlier work on a Y-statement format. We also presented an extension of existing adr-tools to enable command-line tools for handling MADRs as well as a new adr-log tool to generate a list of existing ADRs.
Based on the early feedback, we plan to improve the creation and review process. We also consider to develop a comprehensive yet lean getting started tutorial and quick reference card.
MADRs capture a concrete decision in the context of a single particular project.
However, problems and options may reoccur and diferent options might be chosen in
diferent contexts. For instance when a system runs normally in the absence of partitions,
one choose between diferent trade ofs between latency and consistency [
Acknowledgments This work is partially funded by the BMWi projects SmartOrchestra (01MD16001F) and IC4F (01MA17008G). All links were last followed on February 14, 2018.