Agile Manifestoには以下のように書いてあります。

Working software over comprehensive documentation

動作するソフトウエアは包括的なドキュメントにまさる

ともするとドキュメント軽視と取られかねない宣言です。この宣言を誤って解釈してドキュメントはいらないとなる場合もあるかもしれませんが筆者はそれは間違いだと思っています。この宣言では包括的なドキュメントよりはまさるといっているだけでドキュメントがいらないとは言っていません。

横軸に時間、縦軸に開発効率を取ると感覚的には以下のようになります。人が増えれば開発効率があがるものですがそのようになっていません。ドキュメントがない場合は最初は早いのですが人が増えるにしたがって効率が落ちてきます。

ドキュメントありとなしの場合の開発効率と時間の関係

なぜ初期のプロダクト開発でドキュメントは書かれにくいか

プロダクト開発の初期はPMF(Product Market Fit)をすることが大事です。そうしないとソフトウエアを作ろうがドキュメントを作ろうがまったく無意味でそのソフトウエアもドキュメントも使わず捨てられる事になります。

PMF前のプロダクト開発は人数が少数で作るそれぞれの機能に対して非常に少数(1とか2人とか)で作っており作っているメンバが機能の仕様を全体を理解しています。また機能もユーザの要求によって頻繁にかわるため実際にソースコードを変更しながらユーザの前で試し、よかったらそれが仕様となります。

そのときドキュメントはどうなるでしょうか。次の機能を開発する必要があるのともう動いているソフトウエアがあるので往々にして作られないか不完全なままになります。そうして動くソフトウエアはあるがドキュメントがない状態が作られていきます。

ドキュメントを書かないと何が起きるか

プロダクトが無事PMFをはたし会社も人が増えてきました。そのような状況になるとドキュメントがないことによる弊害が見え始めます。

人が増えるので、昔からいる人のタスクは分割され新しい人に割り振られます。そのとき新しい人にどのように仕様を伝えるのでしょうか。そうです、ドキュメントです。このときドキュメントがないといちいち口頭で説明する必要があり、昔からいるメンバの時間がとられ思うように開発できません。

また、昔からいる人が仕様を覚えていればいいのですが、往々にして細かい仕様は忘れてしまいます。ドキュメントがないことによりどのように動作するのが正しいかわからないプロダクトが生まれます。ユーザの問い合わせ時にも開発者がその仕様を調べたり説明したりして時間がとられます。ドキュメントがあれば防げた事態がうまれます。こうして貴重な時間が消費されていくのです。

GitLabはThe importance of a handbook-first approach to documentationで以下のようにいっています。

An organization that does not put concerted effort into structured documentation has no choice but to watch its team members ask and re-ask for the same bits of data in perpetuity, creating a torturous loop of interruptions, meetings, and suboptimal knowledge transfers.

(意訳) 構造化されたドキュメントの構築に重きを置かない組織は、チームメンバーが同じ事に対して繰り返し聞かれ、ミーティングや知識の伝達で、作業が頻繁に中断されるでしょう。

まさに先ほど書いた状況がおきると言っています。

どうすればドキュメントがかけるようになるか

筆者が思うに以下が必要だと思います。

• トップダウンでドキュメントが必須だと明確にチームに伝える
• 開発する上で書く必要のあるドキュメントの種類を明確にする
• SSOT(Single Source Of Truth)を意識してドキュメントを更新し続ける
• チャットの履歴を一定期間しか残さない

トップダウンでドキュメントが必須だと明確にチームに伝える

経営なりリーダーなりがチームに対してドキュメントが必須だと明確に伝える必要があります。これをしないとチームごとにドキュメントが必要なのかどうかの基準が異なってしまうので対応ばばらばらになり結果的にドキュメントが残らなくなります。ここはチームにまかせるのではなくトップダウンで必要性を説くべきです。

開発する上で書く必要のあるドキュメントの種類を明確にする

ドキュメントが必要だとメンバがわかってもどのドキュメントが必要かわからなければ必要なドキュメントは整備されません。開発に関してのみの一例ですが、以下のように分けるのもありかなと思います。

• Requirement(要求)・Specification(仕様): ビジネスサイドから見たプロダクトが満たすべき要求を書きます。ユーザにとってはどのように実装されるかは興味がありません。例としてはPRD(Product Requirements Document)があります。
• System Design(設計): 要求・仕様を満たすためにどのように実装するか開発者からみた視点のドキュメントです。例としてはDesign Docがあります。

要求・仕様・設計が用語としてはまざりやすく指しているものが人やプロジェクトによって異なる気がしますが、ユーザから見たというのと開発者から見た視点を分けて書き、それぞれのドキュメントがMECEになっていればドキュメントとしてはよいと思います。大切なのは要求・仕様と実装のドキュメントをわけることです。要求・仕様はあるものとして、それをどのように実装するかは開発者次第ということです。実装が変わっても要求・仕様自体はかわらないはずです(もちろん実装方法が困難だったりすれば違う仕様になる可能性はあります)。

上記の他にもプロダクトのMission/Vision/Valueやロードマップなど様々なドキュメントがありますがプロダクトや会社の状況によって必要なドキュメントが異なります。いずれプロダクト開発に必要なドキュメントテンプレート一覧を用意しようと思います。

SSOT(Single Source Of Truth)を意識してドキュメントを更新し続ける

GitLabはDocumentation is the single source of truth (SSOT)といっています。Requirementやは一度かかれたあとに更新されないと、仕様変更があった際に更新されずに古い仕様がドキュメントに残ってしまいます。機能の要件・仕様は修正があったらかならずドキュメントも修正するようにします。

チャットの履歴を一定期間しか残さない

GitLabはLet your Slack or chat messages expire quicklyとし、チャットのメッセージを一定期間しか残さないようにしています。

ドキュメントには以下の種類があります。

• ストック情報: 要求や仕様などまとまった情報
• フロー情報: チャットなどでやりとりされる短い保存を目的としない情報

チャットはフロー情報になるわけですが、ここをいつまでも検索できるようにするとチャットで話した仕様が本仕様となっていまいます。検索が難しいや、SSOTを満たさないなど様々な弊害があります。チャットの履歴を一定期間しか残さないようにして検索不可能にしてストック情報を残すように強制的に促しています。

まとめ

ドキュメントを書くことがいかにプロダクト開発の速度を上げるかを書きました。少人数のときはいいのですが、大人数になると目に見えてドキュメントがないことへの弊害がみえてきます。ドキュメントが整っていない場合はいまからでも遅くないので全体的なスループットを大きくするために整備するべきです。

あとがき1

筆者はドキュメントが整備されなくても大丈夫なプロダクトがあるか考えたことがあります。

少人数のみで開発しておりユーザに仕様を説明する必要がない（たとえばSNSのフィードなど）、の条件があればいらないのではと思っています。その場合でも仕様を説明する必要がない以外の部分で仕様を書く必要があったり、フィード変更の仕様を書いて検証するということもひとつの大事な改善プロセスになり後から振り返る必要もあるので、結局は文化的にドキュメントの整備は必要なのではと思っています。

あとがき2

State of DevOps 2021にドキュメントの品質をあげるにはどのようにしたらいいかの指針がありました。

• Document critical use cases for your products and services
• Create clear guidelines for updating and editing existing documentation
• Define owners
• Include documentation as part of the software development process
• Recognize documentation work during performance reviews and promotions