intltechventures.blogspot.com: 2018-06-20 Wednesday - Some Reading on Lightweight Architecture Decision Records (ADRs)

Wednesday, June 20, 2018

2018-06-20 Wednesday - Some Reading on Lightweight Architecture Decision Records (ADRs)

An interesting article to read first:
Sustainable Architectural Design Decisions
https://www.infoq.com/articles/sustainable-architectural-design-decisions

https://www.thoughtworks.com/radar

Volume 18, May 2018 - Item #1 in the Techniques section of the current ThoughtWorks Radar report recommends adopting "Lightweight Architecture Decision Records"
[note: This is the only Adopt recommendation in the Techniques section, so that is noteworthy in itself]

A historical perspective on the evolution of this ThoughtWorks recommendation:
https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records

...and the associated concept of Evolutionary Architecture
https://www.thoughtworks.com/radar/techniques/evolutionary-architecture

Michael Nygard's thoughts on Lightweight Architecture Decision Records (2011):
http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
"An architecture decision record is a short text file in a format similar to an Alexandrian pattern that describes a set of forces and a single decision in response to those forces.”

Increasing Software Transparency with Lightweight Architectural Decision Records (2017)
https://dev9.com/blog-posts/2017/5/increasing-software-transparency-with-lightweight-architectural-decision-records
(KM: I prefer the naming convention suggested in this article: "YYYYMMDD-NN-Short-Description.md" vs. Nygards simple sequential numbering scheme)

Architecture Decision Records in Action (experience of part of the IBM Watson team adopting ADRs, starting on slide #26, see interesting graphs of ADR growth over time)
https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf
*** see their observations, slide #33
*** see likes/dislikes, slide #36

Homepage of the ADR GitHub organization
https://adr.github.io/

Command-line tools for working with Architecture Decision Records
https://github.com/npryce/adr-tools

See this article too:
https://kevinjalbert.com/start-now-architecture-decision-records/
Interesting: the command line tool also supports being able to generate graphviz output for diagram generation (to visualize linked ADRs)
example: adr generate graph | dot -Tjpg > graph.jpgArchitecture decision record (ADR) examples
https://github.com/joelparkerhenderson/architecture_decision_record

Links to some info on the Alexandrian form (that Michael Nygard references in his article):
http://wiki.c2.com/?AlexandrianForm
https://www.martinfowler.com/articles/writingPatterns.html

A deeper look at Alexandrian form....
https://www.slideshare.net/JoshuaKerievsky/a-timeless-way-of-communicating-alexandrian-pattern-languages
"the masterpiece, "A Pattern Language", by Christopher Alexander"
Note: Christopher Alexander's A Pattern Language (APL) as an important influence in the patterns world.

Also Interesting:
A Decision Modelling Language plugin for Sparx Enterprise Architect
https://github.com/IFS-HSR/ADMentor
https://github.com/IFS-HSR/ADMentor/releases