※ 正確には「知った」のは恐らく半年以上前なんだけど、ちょっと触ったりドキュメントを読んだりした。
設計の基準を明確にして残しておきたい
自分の問題意識としては「設計の決定のための検討、比較などの記録が issue や pull-req に埋れがち」というものがある。またこれらは実はそれほど検索しやすくないし、記録を遡ることもやりやすくない。
この問題は実はかなり長いこと意識としては持っていて、何かみんな困っているはずなんだけどなーと思いつつ、全然情報が見つからずに思い出しては放置、思い出しては放置していたのだが、今回の直接のきっかけは以下のツイート。
考えつつ手を動かす方が問題とちゃんと向き合えてて良いでしょって思ったらちゃんと「問題の分解の仕方を考える」って出てきた。教えるときに参照しやすくてめっちゃ良い！ https://t.co/kjkawSiNJM
— Takafumi ONAKA (@onk) September 25, 2020
このもとは以下の記事で、
時間を区切って設計を打ち切るのはおすすめできない - hitode909の日記
この記事を読んでまさにちょっと前に自分たちのやったことを思い出していて1 、何回めかのトライでようやく ADRs という言葉にはたどり着いていたんだけど、時間がなくてちゃんと掘り下げられずにまた放置していた。
今回やっと時間が確保できたので、ちょっと調べてみてメモを起こしておく。
Technology Radar ではすでに 2017年末から Adopt
Lightweight という言い方がなされており、いわゆるライトウェイトプロセスの中で XP に寄せすぎると欠落しやすくなる「なぜその設計を採用したのか」を、ライトに残すためのドキュメンテーション テクニック のようだ。
Technology Radar では Wiki や Web サイトではなくコードそのものと同期させることができるので Source Control に store することを recommend してる。
※ example を漁ってみると分かるが、比較的仔細なレベルの設計の意思決定を記録しようとしているので、同じリポジトリに入っているのが扱いやすく、また技術的には「収集して再利用」しようと思うと Wiki ではなくファイルとして存在している方がよいので、Technology Radar の言う通りにするのがよさそう。手っ取り早く始めるには Wiki の方がよさそうに見えるけど。
基本のツールは MADR っぽい
おそらくドキュメントの読み書きが低コストで行えればなんでもよいが、昨今の流れだと大半のドキュメントは Markdown を基本に作成されているはずなので、Markdown で書く ADR ( Architectural Decision Records ) ということで MADR という呼び方があるようだ。
おそらく reST でも Asciidoc でも同じように考えられるはずだし、Word や Google Docs でも構わないように感じる。ただ、コードからの距離は遠くない方がよさそう。少なくとも詳細な実装に紐づく部分は。
Templates
ここまでの情報だと、意図していることはなんとなく分かるが、実際に何を書けばよいかがよく分からない。そこでまずは本家で紹介されている Template を漁ってみる。
RFC っぽい重厚さを持つ流派と、よりライトな流派があり、ライトな流派は以下のように似たような内容を扱っているようだ。
| Nygard (2011) | Y-Statements | MADR | 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 | Thoughtworks と Architectural Decision Records | adr.github.io をベースにあれこれ触ってみたけど、恐らく template の決め方はいくつかパターンがあって、その判断基準には
- ドキュメントベースでの意思決定に慣れているかどうか
- 記録の運用が長期間に渡るかどうか
があると思う。
上に挙げた template はあまり status を項目に持っていないんだけど、これがドキュメントベースでレビューして合議で決定するようなスタイルだと status を持っているのは非常に重要になるだろう。また長期間運用されて設計が更新されていくような場合にも status : obsolete などが欲しくなるように思う。
また、
Getting Started with Architecture Decision Records | Blog
では
- 社内の既存のルールに従っているだけの場合には ADR は書かなくてよい
- メール、電話、ミーティングなどを挟んで合意にいたった場合、それを書き起こすことには価値がある
- ほとんどの場合、ADR は他のドキュメントと同じように Wiki やドキュメントシステムに書く
としている。
恐らくドキュメントベースの議論はそれほど重視しておらず、あくまで結果を写し止めておくような印象を受ける。こっちの方がふつうの組織にはよりマッチしそうに見える。少なくとも「始めやすく、残しやすい」のは間違いなさそう。
ただこういうドキュメントは基本的にエンジニア以外は興味を持たないので、共有のドキュメントシステムにあると、メンテナンスや検索、オンボーディングの視点ではイマイチかもしれない。（プロジェクトをまたいで ADR だけを収集するような方法にも向いていない。）
参考
から辿っていける話がとても面白い。この 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
からたどっていける話も面白い。
あと日本語の事例は少ないけど、以下のような感じ。
- 導入した記録ではなく導入“しなかった”記録を残す LADRによるアーキテクチャ意思決定記録のすすめ - ログミーTech
- イベントの文字起こしなので情報の密度は低いが、1年半後に役に立った話など
- この中で紹介されている日本語テンプレートはとりあえず使うにはよさそう moomoo-ya/LADR-template: Lightweight Architecture Decision Recordsを記録するためのテンプレート。
- 〜その意思決定を刻め〜「アーキテクチャ・デシジョン・レコード(ADR)」を利用した設計の記録 - Quipper Product Team Blog
- Quipper では 専用の Issue を使ってそこにぶら下げていく方式。書きやすいかもしれないけど、遡って探すのはやりにくそう。
- Architecture Decision Records導入事例 | Fintan
- 内容というより運用の事例。特に初期はコストとメリットが合わないように見えるというのはとてもリアル。
割と MADR そのままが多いのかな。
いくつかの仕組みが連携する際に、1) 連携元のアウトプット、2) 連携先のインプット、3) 連携先の振る舞いが関係するんだけど、完全な動作を前提にすると 1, 2, 3 の順に実装するしかない。しかし、実際には 3 が決まっていないと 1 が決まらない、なんてことはよくある。そこで 1 の設計を仮置きしておいて、2 はインプットできたものとして適当な値を fixture よろしく置いておいて 3 の実装に取り掛かって、そこから 1 を決定して 1, 2 を実装する、なんてことはよくある。この際、1 の仮置きをちゃんと参照しやすい形で残しておきたい、みたいな話。 ↩