Documenting design decisions in a project fosters understanding while developing and maintaining the software. For that, Markdown Architectural Decision Records (MADR) have been proposed. When setting up a new project, certain decisions have to be done again. With the current MADR approach, how to reuse the knowledge of already taken decisions. This paper proposes Generalized Architectural Decision Records, where knowledge of concrete decisions is stored in a general format to capture “templates” for new decisions fostering reusability.
The remainder of the paper starts with a presentation of GADR (Sect. 2). It is followed by a conclusion and an outlook on future work (Sect. 3). 2
The initial concept is to store the generalized ADRs in a central repository. When a concrete architectural decision has to be taken in a project, that repository is searched for. When a generalized ADR exists, it is copied into the repository of the project. Then, it is extended with pros and cons being valid for the concrete project. When a MADR has to be updated due to new facts or other reasons, a new MADR has to be created, the status of the old one set to “superseded”, and a link to the new one added. History of GADRs and MADRs needs to be tracked with version control. There is no intention to add history to MADR or GADR itself.
We created an initial repository for GADRs in the context of Java on GitHub at https://github.com/adr/gadr-java. We used the GADR for java build tools in JabRef1 and Eclipse Winery2. When creating each ADR, we did not 1 https://github.com/JabRef/jabref/blob/master/docs/adr/0003-use-gradleas-build-tool.md 2 https://github.com/eclipse/winery/blob/master/docs/adr/0023-use-mavenas-build-tool.md need to add new pros and cons of each option. We weighted the pros and cons diferently leading to a diferent decision outcome (Gradle for JabRef, Maven for Eclipse Winery) and the respective justification. A main reason for not modifying the pros and cons is the fact that the decision record was created after the build system was chosen. Nevertheless, this usage of GADR shows that MADRs can be created based on GADRs in real-life projects. 3
This paper presented GADR as first idea to store the general aspects of concrete
architectural decisions using Markdown. The format was extracted from MADR
to enable simple reuse of collected pros and cons. We described one usage of
GADR in the context of JabRef and Eclipse Winery. The next step is to come
up with a well-described development workflow comparable to the work by
Zimmermann et al. [
It is an open topic to structure the collection of generalized architectural decision records. Our current approach is to ofer an index to the GADR repositories at https://adr.github.io/gadr/. Possibly, an updated index of all available GADRs will be added there to ease search for GADRs. Developing a graphical tool presenting all MADRs an their relation to GADRs and thus enabling governance is foreseen.