ADRを一年運用してみた結果と課題
ADRとはArchitectural Decision Recordsの略で、基本的にはソフトウェアに関する決定や経緯を記録しておくものです。Design Docも基本的にはADRと近いです。
参考として、https://adr.github.io/にADRに関する定義が載っていたり、「ソフトウェアアーキテクチャの基礎」という書籍の「13章 アーキテクチャ決定」でADRについて詳しく解説されています。 ただ、すべて定義の通りに書くのではなく、それぞれの組織の都合に合わせてある程度の改造をしても良いと思います。
こちらは弊社のADRで、0番がADRの策定(サンプル)です。ADRを書きたい人はこちらをコピーしてテンプレートにすれば、ステータスやコンテキストなど書くべき内容が分かります。たとえば、メール送信の方式やディレクトリ階層、CI、ログの方式がADRの中で議論されて、決まった決定事項を書いて貯めておきます。
Design Docと同様に書く障壁を低くするために、「コメント募集」といったステータスで不完全でもADRをとにかく書いてもらうように常に宣伝しています。
それぞれのチームで独自のドキュメントを書くことによる影響
ADRと普通の設計資料は何が違うのか疑問に思う方もいるかもしれませんが、実態は普通の設計資料とあまり変わらないと思います。ADRではなくてDesign DocやReadME、PRD、Miro、Figmaに書くところもあります。ただどんな形であれ、ソフトウェア開発ではドキュメントが必要です。 弊社の開発チームもそれぞれのチームでドキュメントを書いていました。
私が所属するCTO室は、いわゆる横軸の改善チームになります。これはチームトポロジーという本に出てくる、ストリームアラインドという機能開発チームに当たりまして、全チームの役割を少しずつ持ちながら広くチームをサポートしています。それ以外のチームはストリームアラインドチームをフォローします。
ドキュメントの話に戻ると、サービス開発やうちのような自社開発受託でよくある状況として、システムAの開発を複数チームが同時並行で行っていて、他のチームは違うシステムBを開発しているとします。
各チームのドキュメントはディレクトリを切ったWikiなどに貯まっていて、チーム内のリーダー的な立場の人が選んだツールが1番使われやすいです。それぞれチーム1・チーム2・チーム3のドキュメントがあって、離れたチーム用のドキュメントもあります。 こういったドキュメント群は良い意味でも悪い意味でも、サイロ化してしまいます。
良い意味では、まずメンバーに最適なツールをチームそれぞれで選定できる主体性があります。また、PdMの管理にも関係していて、マネージャーの人がどういう風に管理したいかというマネージメントにもつながります。さらに、JiraやConfluence、Redmineなど会社の中で許されるツールに合わせて選定されていて、自分たちが作ろうとする機能に最適化しているので効率が良いです。
悪い意味では、チームの部外者に読ませる動機があまりありません。他チームの人が読んですぐ理解できる形にはなっていないですし、統一フォーマットを使っていることも少ないです。 そのため、システム全体の設計を記述するのは不適切になってしまいます。
チームやシステム間で情報共有できるADRを導入
うちの会社では、チームとシステムをまたいだ情報共有のためにADRを用意しました。 ADRをドキュメントの置き場所にすることで、CTO室のような横軸の改善チームを広く全体にも周知できるので、ADRは「みんなのドキュメント・掲示板」という位置付けで宣伝しています。統一フォーマットで認知負荷を下げて情報共有をすることが1番の目的です。
導入のポイントは、
- 導入者が社内から信頼されている
- 導入者が積極的に活用している
- 気合いと根性で3〜4か月ぐらい頑張ってメンテナンスする
の3点です。この辺りはADRに限らずどんなものでも同じことが言えますね。
弊社でのADRの事例を紹介すると、まずアクセスログやアプリケーションログの設計があります。これはチームを横断する決定だったので、問題ではありましたが長年放置されていました。 ただ、ADRで明文化したことで問題が具体化できて、解決への1本の柱が通りました。
他事例では、並行開発する横のチームに迷惑をかけないようにリリースとデプロイを分けられるFeature Togglesという機能をADRで宣伝できました。「ADRを使って広く周知して、こういった機能を開発したいです」「どういう問題点があると思いますか」といったコミュニケーションを各チームと非同期的に取れたので、これはADRをうまく活用できた事例です。
導入前には気付いていなかったのですが、歴の浅いメンバーでも他チームをまたいで横断的同意を得やすいのがメリットです。 ベテランは援助しやすいし、新人でも使いやすいのでかなりWin-Winな関係が作れると思っています。
しかし、何かしらのドキュメントが無いとソースコードを読みながら記録を追うことになります。条件分岐が所々にあったり、意味があるかわからなくて消せないコードがあるとか、データ更新などの運用対処といった浅い解決策が施されていると認知負荷がかなり上がります。特に運用対処をされているとソースコードからは絶対分かりません。
なので、運用・保守しやすいソースコード、個別のドキュメント・コメント、決定プロセスや経緯を記録する機能をソフトウェアには備えていてほしいと思っています。せめて決定プロセスや経緯の記録があると根本的に解決するための方向性が付けやすいです。
何かしら行動を取ったらADRでもDesign DocでもReadMEでも何でも良いので、何か手掛かりを残してくれるといいなと思っています。
ADRの導入障壁になりそうなこと
ただ、ADRなどのドキュメントを導入する際は、ドキュメントが必要だと思う経験を持つ人たちがある程度揃っていた方が良いですね。ドキュメント不要派との力関係が悪いとドキュメントは根付かないと思います。
あと、ドキュメントを書く能力も当然必要になります。ADR自体の読みやすさは書き手にどうしても依存するので、ドキュメントを書く能力はみんなで書きながら育てていく余裕は持っておきたいですね。
気軽に読み書きやコメントができなかったり、履歴が取れないドキュメントツールの導入はやめておいた方が良いです。特にGitはリポジトリにロックされるので気軽に読み書きできません。Wiki系ツールなら大体この辺は揃ってるので大丈夫です。
ADRは横断的な決定事項の記録で、これ以上でもこれ以下でもありません。 チームを超えられるすごい強い力を持っていますが、中身はテンプレートが揃っている単なるWikiという感じです。気軽に読み書きできることが非常に大切で、街の掲示板のような形を目指しています。
パネリストによるドキュメントの運用についてのディスカッション
――ここからは、運営の方で用意したテーマに沿って、先ほど発表していただいた3名のパネリストによるディスカッションを行います。まず一つ目は「設計ドキュメントが導入されるタイミングやフェーズ」ですが、導入のタイミングやフェーズが分かれば、導入を検討している方も今必要なものが分かるかと思います。まず小笠原さんはいかがでしょうか。
小笠原：自分の所属するAdsチームはあまり広告業界の経験の無いエンジニアが多いのですが、立ち上げ期なので議論やトライアンドエラーが1番重要だと思います。そのためにもDesign Documentで広告業界のシステムを知ってる人がイメージを共有してチームの力を上げていく感じですね。
立ち上げ期はDesign Documentが有効だと思います。しかし、ある程度成長してくると関係者も増えてきて、過去のドキュメントの参照のしやすさも含めてADR辺りがより重要になっていくという印象です。
――ADRについては富所さんいかがでしょうか。
富所：チームメンバーのスキルや今までの歴史に合わせて選定して、全体に影響するものだけは統一フォーマットでADRを書くぐらいの縛りの方がうまくいく気がしますね。
今までの経験上、フェーズごとに用意するものが会社全体で決まっている場合がありますが、プロジェクトによって重要度が異なっていて形骸化したのを何度も見てきました。だから、縛りはなるべく薄くして、全体に影響するところだけルールを守るぐらいの方が良いと個人的には思っています。
――田村さんはいかがでしょうか。
田村：5人、10人と人間同士の依存関係が増えて認知負荷が高まりつつあるタイミングが導入すべきタイミングですね。特に、メンバーの理解度が低い内容に関して残していくのがポイントです。
――続いてのテーマは、「各社で使っているドキュメントの使い方」ですが、小笠原さんはADRを使われていますか？
小笠原：ADRは以前使っていましたが、更新されなくなってやめました。今はDesign Documentで基本的に統一しています。Design Documentで議論した完成形としてADRを残しても良いと思いますが、単純に2度手間なのであまり長続きしませんでした。
――富所さんはいかがでしょうか。
富所：うちはCTO室主導で定着しつつありますね。ADRに載せるべきか迷ったらADRに書いて皆に見てもらえばいいというノリなので、それぐらい緩い方が続くのかなという感じです。
――田村さんはいかがでしょうか。
田村：すごいカジュアルなのがDesign Docで、記録にしっかり残してみんなが後で見返せるものはADR、常に更新が求められるものはPRD、という感じです。
視聴者からの質問に答える質疑応答タイムへ
――ここからは、視聴者の方からの質問に回答していきます。まず1個目の質問です。 「ADRにおいて、全体を把握しながらドキュメントを検索しやすくする取り組みをされているのでしょうか」とのことですが、富所さんいかがでしょうか？
富所：基本的にADRは散らばらないように1つのディレクトリ分の配下に並べていて、ナンバリングを統一しています。 なのでそこの中であれば、全体を把握して検索しやすくするのは達成できていると思います。
――ディレクトリコードで工夫されているという形ですか？
富所：そうですね。ディレクトリを分けたいとか、ADRをこっちにも持っていきたいという意見が最初出たんですが、それはアンチパターンになりそうだと思ったので「やめてください」と言った覚えがあります。
――続いて、「ドキュメントの検索のしにくさに関して各社どのように対応されているのでしょうか」とのことで、小笠原さんからいかがでしょうか。
小笠原：自分も知りたいぐらいですね。検索はツール側が頭の良い検索をどうにか作ってくれって思っています。あとLTの方でも話したラベルを付けていますが、付けすぎても逆にわからない部分もあるので、 落としどころは今探り中です。
――田村さんはいかがでしょうか。
田村：ConfluenceもNotionも検索機能が弱いので、構造化したり、関連ドキュメントなどをツリーにして順番に読んでいくようにする感じですね。本当は検索を極力使わないようにドキュメントが構成されていると1番良いので、全体的な量を減らしつつカテゴリー分けをして、書きかけで無駄なものが引っかかるのも避けたりしています。
富所：Confluenceの検索が弱いのはうちも悩んでいますが、macだとRaycastといったツールを使って手元で検索しやすくする工夫はしています。チケットの紐付けは、単純にADRのURLをパーマリンクとして貼って参照する形ですね。あとは、コミットログに参照
先としてURLをそのまま貼って、なぜこのコードが書かれたのかがコード側から読めるような形を作っています。
――続いて、「コードとドキュメントの結びつきをどのように管理されているのでしょうか」とのことですが、まずは富所さんからお願いします。
富所：うちはADR側へ追加のドキュメントとして実装例を添付しています。さっきも言った通り、コミットログからURLを参照する形がメインの使い方ですね。ただ、強制的な紐付けではなく個人の努力みたいな緩い結びつきにはなります。
――他の各社はいかがでしょうか。
田村：そもそもドキュメントを読みに行かせるとソースコードにドキュメントのURLを貼るだけになるので、うちはコメントで説明してリーダブルなコードにしておきます。その中で歴史的な経緯や実装についてどうしても外せない説明は、ドキュメントをソースコードに結び付けていますね。
――小笠原さんの会社でもDesign Documentを繋げるケースはあるのでしょうか。
小笠原：コード上に書くのはあまり無くて、プルリクエストにこのDesign Docを元に作ってますといった感じで書くぐらいですね。 ドキュメントを書く時点で複雑なものをやっているので、ドキュメントが必要になるコードはできるだけ書かないようにしています。
――続いて、「Design Documentなどいろいろなドキュメントがある中、 書き手責任と読み手責任では、どちらに重きがあるのでしょうか」とのことで、まずは富所さんいかがでしょうか？
富所：書き手については、書かれたドキュメントに対してなるべくコメントで突っ込んで、書き手にも育ってもらう感じです。読み手については、読んでいてわからなかったら気軽に相談できるような場所を大量に用意しています。
――田村さんはいかがでしょうか。
田村：エンジニアとして成長するのであれば、ドキュメントを書かざるを得ないという考え方はベースにあります。特に職位が上がってマネージャーやスタッフエンジニアになることを考えると、ドキュメントを書くスキルは必須です。
読み手については、入ったばかりの人たちはドメインや背景もわからないので、「これとこれとこれは最低限読んである程度理解はしておいてほしい。わからなくてもいいからその時に聞いてください」みたいな感じでオンボーディングを充実させていくのが基本になると思っています。
――小笠原さんはいかがでしょうか。
小笠原：自分も完全に同意見で、書き手の方は日々努力です。読み手の気持ちにも書き手の気持ちにもなって読みやすいものを書けるようにスキルアップしつつ、オンボーディングで最低限の前提知識をみんなに持たせるようにサポートした上で読めるようにします。
――続いて、「書いても読まない人が一定数いる中で、読んでもらえるような工夫は何かされているのでしょうか」とのことで、田村さんいかがでしょうか。
田村：ドキュメントを読むことを評価にも含めるのが大事ですね。特別なドメイン知識や背景を理解していないと作れないものがたくさんあるので、ドキュメントを読まないのは必要な業務知識を身に付けていないことに等しいです。昇進のチャンスを失わないように、ドメイン理解のためにもマネージャーなどが読むのをサポートしています。
――富所さんはいかがでしょうか。
富所：読まない人が一定数いるから書いても仕方がない気持ちになられるのが困るので、とにかく書くことが大事だと思います。 読むことに関しては、必要になった時に書いてある場所を誘導できていれば良いですね。
――続いて、「PRDはどういうフォーマットやツールが良いのでしょうか」とのことで、田村さんいかがでしょうか。
田村：フォーマットは先ほどのスライドの8つのポイントの中に記載されているので見ていただければと思います。PRDのサンプルは海外のPdMが結構アップロードしているので参考になると思います。
ツールは会社によってはGoogleドキュメントを使いますが、同時に編集できて履歴が残ってコメントを付けられることを考えると、WikiスタイルのConfluenceかNotionが適していますね。
――続いて、「WikiよりもGitで管理した方がリクエストでレビューしやすかったり、テキストベースで図を書けたり、生成AIにも合わせやすい中で、なぜConfluenceを選んでいるのでしょうか」とのことで、田村さんいかがでしょうか。
田村：Gitはエンジニア以外にはかなりハードルが高いです。Gitで管理するとエンジニアに埋めるのを任せてしまったり、限られたリージョンにしか作用しなくなってしまうので、できるだけ汎用的なツールを使うべきだと思います。
セールスやカスタマーサクセスにドキュメントをGitで書いてもらうわけにはいかないので、フォーマットが統率されていて、職種など関係無く提案できるConfluenceの方が良いと思っています。
――富所さんもかなり頷かれていますね。
富所：まさしくその通りです。セールスの人やGitのアカウントを持ってない人達に気軽に見てもらえず、コメントももらえないのはADRとして欠点だらけになります。検索は辛いかもしれないですが、それ以外はConfluenceが圧勝しているのでConfluenceで十分ですね。
――小笠原さんはいかがでしょうか。
小笠原：完全に同意見です。他の職種の人には障壁が高いのと、 ドキュメント関連がツールによってばらけてしまうのも避けたくて。メルカリはConfluenceを使いながら自分たちでメンテナンスしているWikiやGitHubが一時期ありました。Confluenceが特別良かったわけではないですが、一つにまとめられるならConfluenceにまとめたいですね。
――続いて「どのレベルまでドキュメントする・しないという基準値や設定値について言語化できているのでしょうか」とのことで、富所さんいかがでしょうか？
富所：少し前にADRの中に詳細なクラス設計が書かれていた事例がありましたが、それはADRとしては厳しいと思いました。そういう内容を書く時は、Design Docまたはソースコードのコメントで処理した方が良いと思います。
ただ、ADRの対象がコードの書き方であればコードの書き方がドキュメントに出てくるので、絶対ではありません。あくまでドキュメントの対象に合わせて、その時々で変わるとは思います。
――各社付け加えることはありますか？
田村：「こういう値が設定できます」という内容ならば、ソースコードのコメントとして残せば良いと思います。「この値を使う」「この製品の仕様上はこうなってないといけない」みたいなものはちゃんとドキュメントに残した方が良いです。
影響範囲が広がるほどドキュメント化した方が良いですし、3人ぐらいのエンジニアしか使わない特定のコンフィグファイルの設定値などはドキュメントよりコンフィグファイルに書いてあれば良いという感じです。
――続いて、「ドキュメント文化を浸透させるにあたって、ドキュメントを書くためのお作法・教育について工夫されていることはありますか」とのことですが、富所さんはいかがでしょうか。
富所：ドキュメンテーションを焦点に当てた教育はしていないですね。他の各社もおっしゃってたみたいに書く障壁を下げる取り組みは一部メンバーがやっていますが。
――小笠原さんはいかがでしょうか。
小笠原：教育はしていないですね。過去の参考になるドキュメントを見て真似して徐々に慣れていく感じです。
――田村さんはこれまでのご経験でいかがでしょうか。
田村：まずはドキュメントの必要性と質の良い文章とは何かを理解してもらいます。そのためにAmazonのショップエンジニアの方が書かれた質の高い技術文書を書く方法の書籍を読んでもらったりしています。
――それでは最後に株式会社overflowさんからのお知らせをお願いいたします。
弊社では開発の実践知を繋いでいく役割を担い、開発の発展に貢献するというミッションの下、connpassのコミュニティを運営しております。また、OffersとOffers MGRというサービスもぜひご確認いただけたらと思います。
――本日のイベントはこちらで終了とさせていただきます。 登壇者の皆さん、視聴者の皆さんありがとうございました。
