Markdown Architectural Decision Records: Format and Tool Support Oliver Kopp1 , Anita Armbruster1 , and Olaf Zimmermann2 1 Institute for Parallel and Distributed Systems, University of Stuttgart Stuttgart, Germany {lastname}@ipvs.uni-stuttgart.de 2 Institute for Software, Hochschule für Technik (HSR FHO) Rapperswil, Switzerland olaf.zimmermann@hsr.ch Abstract. 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. 1 Introduction 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 [6], make low-level code comments obsolete. On the other end of the spectrum, however, wide-ranging decisions of high architectural significance are made during development iterations; these decisions are not self-explanatory and not expressed in the code explicitly. An example of such an architectural decision is how to keep user session data consistent and current across Web shop instances. Typically, these kind of decisions are recorded in external documentation files, wikis, or tools [18]. The primary tool of developers, however, is their Integrated Development Environment (IDE) with integrated version control system support. Requiring developers to use more tools has a negative impact on productivity, quality, and motivation to capture architecturally significant decisions: opening another tool requires some setup and training effort and leads to undesired, time consuming context switches. Furthermore, model- and document- centric tools typically do not integrate themselves well in the developer’s toolchain: The documents are not committed in plain text format into the version control system—if versioned along the code at all. Further, the documents might get out of sync with the N. Herzberg, C. Hochreiner, O. Kopp, J. Lenhard (Eds.): 10th ZEUS Workshop, ZEUS 2018, Dresden, Germany, 8-9 February 2018, published at http://ceur-ws.org/Vol-2072 56 Oliver Kopp et al. code base [13]. As a consequence, architectural decision capturing practices and tools oftentimes are perceived as chronophages (time wasters). This holds true particularly for agile and lean developer communities. We therefore can derive the following problem statement: 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 Background and Related Work A large body of research work on capturing architectural decisions exists; the state of the art is for instance surveyed by Alexeeva et al. [2] and by Capilla et al. [4]. Specifically to the context of service orientation and service composition, the SOA Decision Modeling (SOAD) project [17] investigated architectural decisions recurring in SOA design and introduced a seven-step method to identify, make, and capture such decisions. SOAD used a fixed, rather comprehensive meta model. Taking that experience into account, our template and tool, to be introduced in Sect. 3 and 4, are designed in such as way that they are applicable on service-oriented middleware and tool development projects (as evidenced in the validation activity presented in Sect. 5), but not limited to such projects. 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 different formats, including comprehensive and lean ones, are compared by Zimmermann et al. [18]. They also introduce ADMentor, a decision modeling add-in for Sparx Enterprise Architect. ADMentor supports two primary user stories and themes, a) problem space modeling and b) architectural decision capturing. Problem spaces model recurring decisions along with options to be considered. The architectural decision capturing capability then allows architects on projects to keep track of decisions made in a decision log as suggested by the ISO/IEC/IEEE 42010 standard [7] for architecture description. Other features include rich text editing, model linking and refactoring, and reporting/analysis. Decision capturing is streamlined by lightweight decision capturing templates such as Y-Statements [15]; Question, Option, Criteria (QOC) diagrams [9] are supported as well. General best practice recommendations for decision documentation are presented by Zdun et al. [15], including the above mentioned Y-Statement format originally developed for—and first applied in–an industry project setting at ABB [16]. Y-Statements contain the aspects context, concern, the chosen option, other possible options, the expected positive results, and the accepted downsides as well as (optionally) additional decision Markdown Architectural Decision Records 57 1 In the context of , 2 facing 3 we decided for