Background
My organization's backend and frontend teams are starting to use Architecture Decisions Records (ADRs) as part of our decision and documentation process. We were inspired by Lullabot's Andrew Berry's blog post Improving Team Efficiency with Architecture Decision Records. Andrew cited Michael Nygard's article, Documenting Architecture Decisions, as the source of inspiration. Andrew notes that one key goal for ADRs is to provide valuable documentation via the below quote from Micheal's article.
Agile methods are not opposed to documentation, only to valueless documentation.
-- Michael Nygard
My best anecdotal proof of the immediate value of ADRs is while reviewing Lullabot's public ADRs, I discovered their Use Type Tray to improve editorial UX ADR. The Type Tray module is an excellent solution for improving UI/UX for adding new content. The Schema.org Blueprints module now provides a simple Type Tray integration sub-module that automatically generates the content type groupings and icon assignments. The proof here is that if we, as a team and community members, document and share our thought processes and decisions, others can learn and improve upon them.
Recently, a tech lead on my team expressed a reasonable concern that they wanted to ensure all team members understand the architecture decisions behind the Schema.org Blueprints module, sub-modules, and its demo. Currently, only the overarching goals of the Schema.org Blueprints module are defined on the project page. The specific reasoning behind how the module's code base is structured, its dependencies, and the overall technical approach needs to be documented. Providing ADRs for the Schema.org Blueprints module will benefit my team and the Drupal community, and help define the module's current state, provide a way to move the module forward, and hopefully make the module easier to maintain.
Implementation
If ADRs help to onboard new people, it is imperative to make it easy for a team member to scan all the ADRs in a few minutes and then allow them to read through the details in a few hours. Hundreds of ADRs for Drupal decisions could overwhelm new developers. Dedicated ADRs for each module could slow down team members getting up-to-speed. Staying true to the goal of generating simple-to-understand and maintainable documentation, I'm experimenting with grouping related ADRs into a table of contents/index, knowing that each ADR could be split into individual records later. Full ADRs must always be created for complicated, not self-explanatory decisions.
Grouping multiple ADRs into a single categorized document will require keeping the explanation of the decision as simple as possible. For the Schema.org Blueprints, many decisions are based on standard and recommended best practices within the Drupal community. For example, most recommended modules and integrations depend on popular and standard Drupal modules and ecosystems. Therefore, the most basic module decision record is the module's name with a link to its project page and the use case.
Conclusions
Some documentation is better than no documentation.
Adopting an MVP (Minimal Viable Product) approach to documenting the decisions behind the Schema.org Blueprints will not create any additional work. The new single-page work-in-progress DECISIONS.md document allows me to simplify and pair down the existing documentation and provide a canonical place to track notes and decisions. Maintaining ADRs for the Schema.org Blueprints module will help developers and maintainers on-board, contribute, and off-board from the project. The simple exercise of reviewing the current architecture decisions for the Schema.org Blueprints while thinking about the future architecture makes me more comfortable with the growth and maintainability of the project.
Are people using ADRs within their organization or open-source projects? Most decisions are discussed and recorded in our issue queues in the Drupal community. Experienced members of the community know how to search for the history behind a decision. Meanwhile, we can agree that issue queues become overwhelming for new community members when grasping the “why” behind an architectural decision.
I am optimistic that this decision to track decisions using ADRs will enhance the Schema.org Blueprint module's comprehensibility and maintainability.
What do you think about ADRs? What is your experience with ADRs?