Skip to main content

Decision Records

TLDR:​

  • Decisions can be found in the .docs/decisions/* directory.
  • The commands to create and view decisions can be found in the .commands/decisions.mdx file.

Introduction​

Markdown Architecture Decision Records (MADRs) are a method of documenting architecture decisions made during the software development process. By using MADRs, we can maintain a clear, consistent record of why and how choices have been made. This approach not only facilitates better understanding among team members but also aids in future decision-making processes.

MADR Location in Our Project​

All MADRs for our project are stored in the .docs/decisions/* directory. This centralized location ensures that all decision records are easily accessible and maintainable. This directory further is divided into subcategories of decisions.

Benefits of Using MADRs​

  1. Clarity and Transparency: MADRs provide a clear and detailed explanation of architectural decisions, including the context and consequences. This transparency is crucial for new team members and for future reference.
  2. Consistency: By using a standardized format for decision records, we ensure consistency across all documents, making it easier to understand and compare different decisions.
  3. Easy to Track and Update: Markdown files are lightweight and version-controllable, allowing us to easily track changes over time and keep records up-to-date.

Creating and Viewing MADRs​

While we managed to simplify the creation and viewing of MADRs via the make decisions-new and make decisions-preview commands (also found in the .commands/decisions.mdx) file, under the hood we use two tools, and optional third tool (VSCode extension) for quality of life.

Creating MADRs via madr-tools​

We utilize madr-tools for creating MADRs. This tool simplifies the process of creating, updating, and maintaining architecture decision records. Some key features include:

  • Template-based record creation for consistency
    • Template can be found in .docs/decisions/template.md
  • Automatic file-naming based on previous MADR number.

Viewing MADRs via log4brains​

We utilize log4brains for viewing MADRs. While they have a mechanism to generate MADRs, we prefer to use madr-tools for this. However, they do have a nice web interface for viewing MADRs, and we use this for our make decisions-preview command.

ADR-editor via ADR Manager VSCode extension​

We utilize the ADR Manager VSCode extension for editing MADRs This extension provides a nice interface for editing MADRs.

In order to use this, you will need to right-click on the generated MADR file, and select Open ADR Manager on This File.

Alternatively, while viewing the MADR record, you can press CMD+Shift+P (or Ctrl+Shift+P) and type ADR Manager: Open ADR Manager on This File.

Note that this dev container should already have the extension pre-installed.

Quick Command Access​

For convenience, we have set up a quick way to run MADR commands. You can access these commands by opening the .commands/decisions.mdx file using Runme. This setup streamlines the process of managing MADRs, making it more efficient for the team.

Learn More​

To understand more about the Markdown Architecture Decision Record format, visit https://adr.github.io/madr/. This resource provides comprehensive information on the structure and purpose of MADRs.