プロダクト開発をする上で、ドキュメントを残し育てることは非常に重要です。
しかしながらドキュメントといってもどういうものが、あれば良いのかわからないという理由で書かないというケースも多いと思います。
私も制作会社で短期間・少人数のプロジェクトが多かったのですが、サービス開発のようにメンバーの入れ替わりが多かったり、人が増えたりするプロジェクトに関わるようになるとドキュメントに救われるようになってきました。
スタートアップだからドキュメントが無い。という話はよく聞きますが、最近ではスタートアップだからこそドキュメントは残すべきというくらいの考えを持っています。
この記事ではプロダクト開発をする上で、ドキュメントにはどういう情報を残すと良いのか、ドキュメントがあるとなぜ良いのかを紹介したいと思います。
そもそもドキュメントがなぜ必要なのか
ドキュメントを書く習慣がない場合、「話したほうが早い」と思われる方がいらっしゃいます。
それ自体は事実なのですが、ではすぐに10人に説明すること、3ヶ月後に新しく入った5人に説明する必要が出てきた場合話す事はもうこれは「早い」にすらなりません。
また口頭では認識の齟齬も起きやすいですし、初めて聞く情報が多い場合は理解すら正しくできません。もちろん話し手が聞き手の理解度を把握しながらコミュニケーションを取るというのは非常に困難です。
チームのメンバーが増えてくると一人が情報を把握することが難しく、リスクも高くなるばかりなので非同期で最新の情報を確認・編集ができるほうが健全となります。
特に昨今ではリモートワークが増えてきて非同期の開発が当たり前になってきているので、ドキュメンテーションの必要度合いも一緒に上がってきています。
またドキュメンテーションの有無はレビューの品質にも影響を与えます。
コードもデザインもそうなのですが、レビュー対象の文脈やなぜこうなっているの背景がわからないと、レビューワーも自信を思ってレビューができず、当たり障りのない議論しかできなくなってしまいますし、チームに入ってきたばかりのメンバーもレビューにしづらくなります。
ドキュメントがない場合、どうしてもいきあたりばったりな議論になりやすく、目的とは異なった議論にも拡散しやすいため、予め決まりごととなるドキュメンテーションがあることでコミュニケーションの衝突も回避しやすくなります。
またドキュメンテーションがあることで、仕様や目的を俯瞰して見ることができ改善する際も現実的な発想でスムーズに議論ができますので、改善スピードも上がります。
このようにドキュメントがある事でステークホルダーや別のチーム・職種とも相談がしやすくなり、特定の誰かをボトルネックにするリスクを減らせます。
ドキュメントがなくても良い場合
正直ほとんど無いと思います。
自分ひとりでの開発や誰か一人が責任をきちんと持つ体制でその選択をした場合はなくても良いかもしれません。
またなんらかの理由で誰も管理ができず、実装のマニュアルにもならないと想定される場合は無くても良いでしょう。ただしこの場合はドキュメントの必要性よりプロジェクトの進め方を見直すきっかけに持っていくほうが良い結果につながるかもしれません。
よくあるアンチパターンとしては、ドキュメントを残すかの判断もせずにプロジェクトを進めて誰も全体像を把握できず、炎上してしまい誰をアサインしても復旧できないような状態になることです。
まずはドキュメントが必要かどうかはきちんと判断をするというのが大事だと思います。その上でなくても良いという流れにしないと大勢を不幸にする結果になりやすいです。
Design Docで記載するもの
Design DocとはGoogleをはじめとしたソフトウェア開発の企業で使われるもので、あるソフトウエアについて、何を・なぜ・どのように作るかを記したものです。
Design Docでは以下のような内容が記載されます。
- 背景、目的(Why)
- 設計(How)
- メンバー(Who)
- セキュリティやリスクについての考察など
- テスト、モニタプランなど
細かい項目はもっとあるかもしれませんが、良く見るドキュメントはこのあたりが記載されています。
私が作る場合は以下のような内容で書くことが多いです。
基本の情報
- プロダクトの背景・機能開発の目的
- 誰の何の課題を解決するものなのか
- PRD、リーンキャンバス、インセプションデッキのどれか
- プロジェクトの参加者
- コミュニケーション場所（slackのチャンネルなど）
- 開発リポジトリ
- プロジェクトのタスクの場所
- 用語集
- 関連するチーム・関係者、機能
開発上検討した情報
- 画面遷移図
- figmaなどデザインツールのURL
- システムの技術的概要
- アーキテクチャー図
- スコープ
- 選定した解決手段について
- 選定の根拠、トレードオフ
- PoCの内容と結果
- PoCをさられる場所
- 選定しなかった解決手段について
- 手段の概要
- 不採用の根拠
- 外部依存の概要
- 考えられるリスク
- リスクへの対応策
- セキュリティ観点の考察
- 考えられるリスク
- テスト観点からの考察
- 運用時の注意・考慮
- 評価の指標・設計
- 障害の発見と復旧手法
参考にした記事
【翻訳】Googleのエンジニアがソフトウェア開発する時に必ず書くドキュメント「Design Docs at Google」
実際のDesign Docの例
ドキュメントに対しての思い
ドキュメントの無いプロジェクトとあるプロジェクトでは、メンバーが活躍するスピードが大きく変わります。大きな規模のプロジェクトあればあるほどドキュメントを残す難易度が上がりますが必要性も高まります。
過去に自分や他人書いたコードをメンテナンスして，非常に苦しめられたことが何度かありました。
これは適切なレビューができなかった/されなかったのが一つの要因と思っています。
ただ動くものを作るだけなら、ドキュメントの必要性は少なくなりますが安全に作り続けるものを作るにはドキュメントはとても重要です。
コードのメンテナンス性・再利用性を高めるにはどうあるべきかみたいな議論をチーム内で繰り返すだけれもチームの練度が高まります。
最後に
作りたい物をきちんとドキュメントに作ることによって、問題を整理し目標を明確化できます。
ただドキュメントを作ることを目的にしだすと、メンテナンスにコストが掛かりチームの速度が落ちたりするので注意は必要です。
どうドキュメントを運用するかも大事なので、またこのあたりは別の記事で書けたらと思います。
ドキュメントがある事で人を巻き込みやすくなり、判断を間違えたときにも誰かに指摘してもらえたり、後戻りしやすくなるので絶望的な状況を避けやすくなります。
ただドキュメントがある事で気持ちの良いチーム開発がしやすくなるので、ぜひドキュメントを残す文化がもっと普及してほしいと思います。