estieではなぜドキュメントを書くのか？
よくあるパターンとして、
「すごいクールな機能を考えたからすぐリリースできるだろう」
「いや、その機能が影響を与える範囲がわからないから、 とりあえず調査のために3ヶ月欲しい」
みたいなことが起きます。
あとは、
「この機能はいらないから消したい」
「でも誰が実装したのか全くわからない」
「何のためにあるのかすらわからなくて、とりあえずよくわからないから消せない」
みたいなことも起きます。
こういうことを防ぐためにドキュメントを書くのですが、事業の立ち上げの時期はかなり高速に作っているのでドキュメントを書かないケースが非常に多いです。ですが、1〜2年経つといつの間にかドキュメントが無いせいで、大変苦労することになります。
例えば、よくわからない機能がいくつか残っていて、これは残したままにすべきかどうかがわからず困るのが現状です。せめて当時の記録さえあれば何とかなりますが、当時書いていた人も記録も無くて、どうしようもないというのがよくあるパターンですね。
しかし、ドキュメントは過小評価されている印象があります。組織全体やチームで複数のチームなどの広範囲に長期間良い影響を与える唯一の手段としてドキュメントは必要です。
ドキュメントは、思考や決定、トレードオフなどを残すために書きます。ただ、多くの人に読んでもらうためにはうまく書く必要があるのが難しい所です。 みんなはドキュメントを読んでいるのではなく情報をちゃんと摂取しているので、うまくないものは食べないですね。美味しいラーメンじゃないと食べてくれないのと同じように、良い情報じゃないとみんな摂取してくれないという基本原則があります。
良いドキュメントの書き方とは？
では、良いドキュメントの書き方とは一体何でしょうか。一般的に良い方法は1〜3時間で方向性を明確にした草稿を書いて、ステークホルダーに方向性を確認してフィードバックを得るというシンプルなやり方です。
文章を編集する時には、読み手の気持ちになって分かりやすさを担保すること、不必要で邪魔な要素を極力取り除くこと、箇条書きを最低限にして結論にフォーカスすること、自分の時間より相手の時間を大切にすること。この基本が無いとかなり読みにくいです。あとはフィードバックが欲しいと思った時も、単にみんなにフィードバックくださいって言うだけではやってくれません。そうではなくて、「私はAだと思うのですが、Bという観点ってあり得ますか」といった感じで、具体的に絞って求めないと良いフィードバックは得られないですね。
estieにおけるドキュメントの使い分け
estieで運用されているのは主にDesign Doc・ADR・PRDです。基本的にはRequest for Comment、つまりコメントを求める仕組みになっています。ただ、いつ何を書くべきか全くわからないということが起きるのでそれぞれのドキュメントについて説明していきます。
まずDesign Docは、最初に何か始める前にフィードバックを求めるのが目的です。コンテキストやアプローチ、トレードオフなどを記載して、「こういうことを雑にやりたいんだけど、みんなどう思う？」とRequest for Commentでフィードバックをもらって、 やりたいことに対する時間を短縮するためのものです。
コメントをもらったのに何も反応していなかったり、ステータスが変わっていなかったり、ボロボロの状態で放置されていたりすることはよくあるので、ドキュメントが溜まりすぎないようにメンテナが反応を促す形でメンテするようにしています。方向性が決まったら更新の必要は無くなるので、適切な場所(ディレクトリやスペース)に移動させて対処しています。
Design Docはハードルが低くないとみんなが書いてくれないので、形式は自由でコメントさえできれば良いという状態です。Design Docでは、数年前に書かれたまま放置・散乱していることが結構あるので、そういったゴミを掃除しております。
次のADRは、設計の基準や判断を明確に残しておくためのものです。更新し続けるという意味ではなくて、あくまでも意思決定の記録です。たとえば複数の選択肢A・B・Cの中で、なぜBを選んでCを選ばなかったのかも残すようにしてあります。なぜ選ばなかったのかが明確でないと同じような提案が繰り返し上がってきてしまうので、記録しておけばそれを防ぐことができます。
ADRには、主にタイトルやステータス、コンテキスト、決定、結論がどうなっているかをちゃんと残すようにしてあります。選んだ理由を後で見返せるので、選んだ人がいなくなっていても「当時はこういう状況だったからこっちの選択肢が適切だったけど、2年経って状況も変わっているから当時の決定を今変えよう」ということもできます。
最後はPRDについてですが、Product Requirements Documentの略で製品要求仕様書という意味です。estieでは当初は企画書として、Design Docという名前でDesign Docに近い形で運用されていましたが、実際のDesign Docとは全然違ったので今はPRDになっています。
PRDは現在の製品の仕様や機能の仕様を表しているので、できるだけ基本的には更新しなければならない方針でやっております。ただ、結構試行錯誤していて、製品仕様書となると本当は仕様が決まってから実装が変わるべきなんですが、意図しない変更があった場合もちゃんと記録を残すために、更新が非常に難しくなっています。
- つまりどういうこと？
- なぜ解決が必要か？
- 誰が使うためのもの？
- どのように実行していく？
- 何の問題を解決する？
- どう解決したかわかる？
- 端的に言うと何？
- いつリリースできる？
といった項目を埋めていって、その機能単位のPRDを作っていきます。
方向性がきちんとしていないとドキュメントとして意味を成さないので、
- 問題志向か？
- 時間軸が現実的になっているか？
- 成功基準が明確か？
- 読みやすいか？
- 方向性が伝わっているか？
が明確になるように運用しています。こういったことをやらないと、誰も読んでくれない文書がたくさんできて、誰もメンテしなくなってゴミが残って月末を迎えるので、 しっかりと書いてもらうように促しています。
以上まとめとして、estieで運用しているドキュメントは3つあって、それぞれいつ書くか書かないかが決まっています。Design Docであれば提案するとき、ADRであれば何かの決定・変更が発生するとき、PDRであれば製品に新しい仕様が追加されるときで、何のためにあるのか、どう更新していくのかも管理されています。
パネリストによるドキュメントの運用についてのディスカッション
――ここからは、運営の方で用意したテーマに沿って、先ほど発表していただいた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というサービスもぜひご確認いただけたらと思います。
――本日のイベントはこちらで終了とさせていただきます。 登壇者の皆さん、視聴者の皆さんありがとうございました。
