Adsチームでのドキュメント運用
メルカリは主にドキュメントツールとしてConfluenceを使っていて、私が現在所属するAdsチームもそれを利用しています。Adsチームは私が入るまでかなり少人数でやっていたので、ドキュメンテーションよりも実際にコードを書いて動かすところに注力していました。
初期の頃はランダムにドキュメントを作成したり、個人で自由にディレクトリ構成を考える形で、組織としてのルールを作らずに運用していたんです。その後事業やチームが拡大するにつれて、ドキュメントの整理のためにカテゴリ分けをするようになりました。カテゴリ分けについては明確な狙いはないですが、既存のドキュメントを分けているというのが現状です。
ただ、ドキュメントによっては複数の場所に関わっていて綺麗にカテゴリ分けできないものがいくつか出てきているので、ラベルで検索性を上げる運用をお試しでしています。
また、各カテゴリでルールを明記して運用するようにしています。
たとえば、
- このディレクトリはDesign Docを保存する場所である
- このドキュメントのディレクトリ以下は最新の情報の更新はしない
といったように、古くなったら自動的もしくは誰かの手でアーカイブされるようなことを明記しています。
Design Docの運用状況
我々のチームがDesign Docを運用する1番の目的は、課題点の明確化や共有と議論の活性化です。 できるだけDesign Docを書く障壁を下げられるように取り組んでいます。
そのため、Design Docを書く条件も特に設けてはいません。新しいサービスを作る時や新機能を追加する時はもちろん書きますが、日々の運用や既存機能の修正についても議論したい時には、小規模なドキュメントを箇条書きでもいいので書いて、それを元に議論したりしています。
フォーマット自体はありますが、 全項目を埋める必要はなく、足したり消したりして良いという結構自由なルールで運用しています。 例外はありますが、基本的には書いた人がAcceptedのようなステータスを随時判断して良いですし、Acceptedでなくても開発を開始して問題ありません。
特にDesign Docを乗り越えないと開発できないルールにはしていなくて、Design Doc上で議論して、細かいところは実装しながらプルリクエスト上で詰めていったりしています。
あと、Accepted後や開発完了後のDesign Docの更新は不要にしています。 情報が古くなっても良くて、あくまでもスナップショットであるというのを全員の認識として運用しています。
Design Docの運用を定着化させる取り組み
Design Docを書いた方が開発がスムーズになったり、スキルアップにつながる「お得」な状態を作るのが一番の狙いでした。Design Docによって、他人の意見や自分の中で抜けていた考慮点をレビューを通じて指摘してもらえます。
また、知らなかった技術や他チームの同じような事例を知れるので、自分で考えていた解決策以上のものが得られる体験ができるようにしたいと思っています。あとは、 Design Docのレビューを通じてチーム内で認識を一致させて、その後のコードレビューがスムーズになるようにしていますね。
Design Docを定着させるためにデイリーで相談できるmeeting slotを用意しました。チーム内ではWai Wai Sync meetingと呼んでいて、Design Docに関わらず仕様の共有や コーディングの質問など特に目的は設けずに、どんな話題でもみんなで話して解決する場を作っています。ここの場では、ドキュメント作成途中でもレビューできる空気や場所作りを意識しています。
完全に完成されたDesign Docでなければレビューしないわけではなくて、荒い状態でも困っていることを予め相談できる場を設けています。なので、「まだ3割ぐらいですが、方向性が合っているか相談させてください」とか、「2つの方針どっちが良いですか」みたいなことを、本当に荒いドキュメントで箇条書きの文章でも全然良いので、議論して方向性を定めた上で、Design Documentで文字にするところを「Wai Wai Sync meeting」で行っています。
Design Documentを開発するために乗り越える関門にはしたくなくて、 議論をして合意形成をすることを目的としているので、Declineというステータスが過去一度も使われてないのは、自分としては結構良いことだと思っています。
Design Doc関連の困りごと
ドキュメント関連の困りごとの一つとして、 不可逆な技術選定などに関するDesign Documentなどはパフォーマンスの計測やコストの妥当性を明確にする必要があるので、それに関するレビューは関係者も増えて時間がかかりがちなのがあります。
これに関してあまり明確な解決策は見出せていないですが、事前にApproverやApproveの条件を整理して、あとは口頭で共有といった地道な調整をしているのが現状です。
また、Design Documentを細かいものでもどんどん書くようにしていることもあって、大小様々なドキュメント、Statusがドラフトのままだったり、議論がすでに終わっていたり、中途半端に終わっているものがいくつか散らばっている状態があったのが2個目の困りごとです。
それらを整理するために議論し尽くしていたり機能自体がなくなったもの、過去施策のドキュメントなどは、Archivedなディレクトリに移した時期がありました。必要なものだったらrevertするのを前提として、不要そうなものは一気にArchivedにしていました。このように認知負荷を下げて定期的に整理するのは重要です。
あとDesign Documentは更新不要と先ほど言いましたが、それとは別でシステムアーキテクチャなどのドキュメントは常に最新のものを維持したいと思っています。更新漏れはドキュメントの永遠の課題で、 常に最新のものを維持するのは難しいです。
過去にはDocumentation Weekといったドキュメントをしっかり書くように促進する週を設けたりしましたが、 あまり上手くいきませんでした。 今のところはDocumentationもProject closeを条件にしたり、エピックの終了条件にしたりして、ドキュメントが古くならずちゃんと更新するようにしています。
まとめになりますが、Design Documentを通じて議論を活性化することが運用の最大の目的です。そのためにドキュメントを作成する障壁をできるだけ下げています。そして、定期的にレビューする場を設けて早期かつ頻度高くレビューできるようにしていて、ドキュメントの更新漏れに関しては今も試行錯誤中です。
パネリストによるドキュメントの運用についてのディスカッション
――ここからは、運営の方で用意したテーマに沿って、先ほど発表していただいた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を併用している時が一時期ありました。Confluenceが特別良かったわけではないですが、できるかぎりツールはまとめたいです。
――続いて「どのレベルまでドキュメントする・しないという基準値や設定値について言語化できているのでしょうか」とのことで、富所さんいかがでしょうか？
富所：少し前にADRの中に詳細なクラス設計が書かれていた事例がありましたが、それはADRとしては厳しいと思いました。そういう内容を書く時は、Design Docまたはソースコードのコメントで処理した方が良いと思います。
ただ、ADRの対象がコードの書き方であればコードの書き方がドキュメントに出てくるので、絶対ではありません。あくまでドキュメントの対象に合わせて、その時々で変わるとは思います。
――各社付け加えることはありますか？
田村：「こういう値が設定できます」という内容ならば、ソースコードのコメントとして残せば良いと思います。「この値を使う」「この製品の仕様上はこうなってないといけない」みたいなものはちゃんとドキュメントに残した方が良いです。
影響範囲が広がるほどドキュメント化した方が良いですし、3人ぐらいのエンジニアしか使わない特定のコンフィグファイルの設定値などはドキュメントよりコンフィグファイルに書いてあれば良いという感じです。
――続いて、「ドキュメント文化を浸透させるにあたって、ドキュメントを書くためのお作法・教育について工夫されていることはありますか」とのことですが、富所さんはいかがでしょうか。
富所：ドキュメンテーションを焦点に当てた教育はしていないですね。他の各社もおっしゃってたみたいに書く障壁を下げる取り組みは一部メンバーがやっていますが。
――小笠原さんはいかがでしょうか。
小笠原：教育はしていないですね。過去の参考になるドキュメントを見て真似して徐々に慣れていく感じです。
――田村さんはこれまでのご経験でいかがでしょうか。
田村：まずはドキュメントの必要性と質の良い文章とは何かを理解してもらいます。そのためにAmazonのショップエンジニアの方が書かれた質の高い技術文書を書く方法の書籍を読んでもらったりしています。
――それでは最後に株式会社overflowさんからのお知らせをお願いいたします。
弊社では開発の実践知を繋いでいく役割を担い、開発の発展に貢献するというミッションの下、connpassのコミュニティを運営しております。また、OffersとOffers MGRというサービスもぜひご確認いただけたらと思います。
――本日のイベントはこちらで終了とさせていただきます。 登壇者の皆さん、視聴者の皆さんありがとうございました。