Architectural Decision Records を知った

※ 正確には「知った」のは恐らく半年以上前なんだけど、ちょっと触ったりドキュメントを読んだりした。

"life is a succession of choices, what is yours?" by https://unsplash.com/@ivalex

設計の基準を明確にして残しておきたい

自分の問題意識としては「設計の決定のための検討、比較などの記録が issue や pull-req に埋れがち」というものがある。またこれらは実はそれほど検索しやすくないし、記録を遡ることもやりやすくない。

この問題は実はかなり長いこと意識としては持っていて、何かみんな困っているはずなんだけどなーと思いつつ、全然情報が見つからずに思い出しては放置、思い出しては放置していたのだが、今回の直接のきっかけは以下のツイート。

このもとは以下の記事で、

時間を区切って設計を打ち切るのはおすすめできない - hitode909の日記

この記事を読んでまさにちょっと前に自分たちのやったことを思い出していて1 、何回めかのトライでようやく ADRs という言葉にはたどり着いていたんだけど、時間がなくてちゃんと掘り下げられずにまた放置していた。

今回やっと時間が確保できたので、ちょっと調べてみてメモを起こしておく。

Technology Radar ではすでに 2017年末から Adopt

Lightweight という言い方がなされており、いわゆるライトウェイトプロセスの中で XP に寄せすぎると欠落しやすくなる「なぜその設計を採用したのか」を、ライトに残すためのドキュメンテーション テクニック のようだ。

Technology Radar では Wiki や Web サイトではなくコードそのものと同期させることができるので Source Control に store することを recommend してる。

※ example を漁ってみると分かるが、比較的仔細なレベルの設計の意思決定を記録しようとしているので、同じリポジトリに入っているのが扱いやすく、また技術的には「収集して再利用」しようと思うと Wiki ではなくファイルとして存在している方がよいので、Technology Radar の言う通りにするのがよさそう。手っ取り早く始めるには Wiki の方がよさそうに見えるけど。

基本のツールは MARD っぽい

おそらくドキュメントの読み書きが低コストで行えればなんでもよいが、昨今の流れだと大半のドキュメントは Markdown を基本に作成されているはずなので、Markdown で書く ARD ( Architectural Decision Records ) ということで MARD という呼び方があるようだ。

おそらく reST でも Asciidoc でも同じように考えられるはずだし、Word や Google Docs でも構わないように感じる。ただ、コードからの距離は遠くない方がよさそう。少なくとも詳細な実装に紐づく部分は。

Templates

ここまでの情報だと、意図していることはなんとなく分かるが、実際に何を書けばよいかがよく分からない。そこでまずは本家で紹介されている Template を漁ってみる。

RFC っぽい重厚さを持つ流派と、よりライトな流派があり、ライトな流派は以下のように似たような内容を扱っているようだ。

Nygard (2011) Y-Statements MARD Alexandrian Pattern
      prologue
context context context discussion ( context )
status      
  facing decision drivers  
    consider options  
decision we decided decision outcome ( consequences posi / nega ) solution ( decision )
concequenses alternatives not chosen   results ( consequences )
  to achieve    
  accepting pros and cons of options  

だいたいどれも

  • context
  • options
  • decision
  • pros / cons of options

みたいな感じになっている。

adr.github.io がおよそ 3, 4 年前にリリースされており、この頃からこうしたドキュメンテーションの話は一部で盛り上がっているっぽい。しかし Nygard の post は 2011 年であり、もう10年前の話になっている。

XP やライトウェイトプロセス、アジャイルなどの盛り上がりが一段落し、そうは言っても実践的に役に立つドキュメントの手法についても意見が出始めたのがこの頃なんだろうか。

examples

こうして見るとけっこう細かいレベルの記述になっていることが分かる。

処理系

書くには

とりあえず sh script の以下のものが手頃で扱いやすい。これは Markdown を基本にしている。

いろいろな言語に移植されているが、けっきょくのところ決まったテンプレートに従って Markdown を書けばよいだけなので、あまり凝った道具は要らないと思う。

読むには

Markdown で書くと決めたら Markdown なのでそのまま読めなくもないが、

なんかでもよさそう。また多くの人が手軽に読めるようにするという意味では

などを使って Web サイトを起こすのもよいのではないかという気がしている。Wiki と違ってファイルなので、どこかでまとめたり、統一的な UI をもたせたりということもそれほど難しくないはず。

template の種類と組織の回し方と記録の残し方

ということで Lightweight Architecture Decision Records | Technology Radar | ThoughtworksArchitectural Decision Records | adr.github.io をベースにあれこれ触ってみたけど、恐らく template の決め方はいくつかパターンがあって、その判断基準には

  • ドキュメントベースでの意思決定に慣れているかどうか
  • 記録の運用が長期間に渡るかどうか

があると思う。

上に挙げた template はあまり status を項目に持っていないんだけど、これがドキュメントベースでレビューして合議で決定するようなスタイルだと status を持っているのは非常に重要になるだろう。また長期間運用されて設計が更新されていくような場合にも status : obsolete などが欲しくなるように思う。

また、

Getting Started with Architecture Decision Records | Blog

では

  • 社内の既存のルールに従っているだけの場合には ADR は書かなくてよい
  • メール、電話、ミーティングなどを挟んで合意にいたった場合、それを書き起こすことには価値がある
  • ほとんどの場合、ADR は他のドキュメントと同じように Wiki やドキュメントシステムに書く

としている。

恐らくドキュメントベースの議論はそれほど重視しておらず、あくまで結果を写し止めておくような印象を受ける。こっちの方がふつうの組織にはよりマッチしそうに見える。少なくとも「始めやすく、残しやすい」のは間違いなさそう。

ただこういうドキュメントは基本的にエンジニア以外は興味を持たないので、共有のドキュメントシステムにあると、メンテナンスや検索、オンボーディングの視点ではイマイチかもしれない。(プロジェクトをまたいで ADR だけを収集するような方法にも向いていない。)

参考

Architecture Decision Record Template: Y-Statements | ZIO’s Blog: Architectural Decisions, (Micro-)Services and More

から辿っていける話がとても面白い。この Y-Statements も original は medium の post である 2020 年ではなく、SATURN という Software Architecture Community の 2012 年の際に発表されたものらしい。

こうして見てみると ADRs だけではなく AD ( Architectual Decisions ) や AKM ( Architectural Knowledge Management ) という言葉も多く登場してくるのが分かる。ADR という言葉だけでなく、その辺も掘っていけるといいのかな。

(1) SATURN: A Software Architecture Community - YouTube

もう少し全体感がまとまったものは

Documenting Software Architecture – @hgraca

からたどっていける話も面白い。

あと日本語の事例は少ないけど、以下のような感じ。

割と MARD そのままが多いのかな。


  1. いくつかの仕組みが連携する際に、1) 連携元のアウトプット、2) 連携先のインプット、3) 連携先の振る舞いが関係するんだけど、完全な動作を前提にすると 1, 2, 3 の順に実装するしかない。しかし、実際には 3 が決まっていないと 1 が決まらない、なんてことはよくある。そこで 1 の設計を仮置きしておいて、2 はインプットできたものとして適当な値を fixture よろしく置いておいて 3 の実装に取り掛かって、そこから 1 を決定して 1, 2 を実装する、なんてことはよくある。この際、1 の仮置きをちゃんと参照しやすい形で残しておきたい、みたいな話。 

More

Categories

Tool 日々 Web Biz Net Apple MS ことば News Unix howto Food PHP Movie Edu Community Book Security Text TV Perl Ruby Music Pdoc 生き方 RDoc ViewCVS CVS Rsync Disk Mail FreeBSD Cygwin PDF Photo Zebedee Debian OSX Comic Cron Sysadmin Font Analog iCal Sunbird DNS Linux Wiki Emacs Thunderbird Sitecopy Terminal Drawing tDiary AppleScript Life Money Omni PukiWiki Xen XREA Zsh Screen CASL Firefox Fink zsh haXe Ecmascript PATH_INFO SQLite PEAR Lighttpd FastCGI Subversion au prototype.js jsUnit Apache Trac Template Java Rhino Mochikit Feed Bloglines CSS del.icio.us SBS qwikWeb gettext Ajax JSDoc Rails HTML CHM EPWING NDTP EB IE CLI ck ThinkPad Toy WSH RFC readline rlwrap ImageMagick epeg Frenzy sysprep Ubuntu MeCab DTP ERD DBMS eclipse Eclipse Awk RD Diigo XAMPP RubyGems PHPDoc iCab DOM YAML Camino Geekmonkey w3m Scheme Gauche Lisp JSAN Google VMware DSL SLAX Safari Markdown Textile IRC Jabber Fastladder MacPorts LLSpirit CPAN Mozilla Twitter OpenFL Rswatch ITS NTP GUI Pragger Yapra XML Mobile Git Study JSON VirtualBox Samba Pear Growl Mercurial Rack Capistrano Rake Win RSS Mechanize Sitemaps Android JavaScript Python RTM OOo iPod Yahoo Unicode Github iTunes God SBM friendfeed Friendfeed HokuUn Sinatra TDD Test Project Evernote iPad Geohash Location Map Search Simplenote Image WebKit RSpec Phone CSV WiMAX USB Chrome RubyKaigi RubyKaigi2011 Space CoffeeScript Nokogiri Hpricot Rubygems jQuery Node GTD CI UX Design VCS Kanazawa.rb Kindle Amazon Agile Vagrant Chef Windows Composer Dotenv PaaS Itamae SaaS Docker Swagger Grape WebAPI Microservices OmniAuth HTTP 分析基盤 CDN Terraform IaaS HCL Webpack Vue.js BigQuery Middleman CMS AWS PNG Laravel Selenium OAuth OpenAPI GitHub UML GCP TypeScript SQL Hanami Develop Document Jekyll