ドキュメントはリーダーのアウトプット#
極端だと思いつつ、 PO (あるいは PdM) やチームリーダーの真のアウトプットは、ミーティングで交わされる会話でも Slack のスレッドでもなく ドキュメント である、と言い切ってもいいかもしれない。
口頭やチャットで交わした話の内容は、すれ違うたびに変形し、やがて消える。しかしながら、文字として残した意思決定と背景は、チームが非同期に連携するための羅針盤となる。
もう少し具体的に言えば、例えばスクラム開発においてはチームが自律的に駆動できることがポイントとなるけれども、これを別の側面から言い換えれば リーダーに直接問い合わせることなく、チームメンバーそれぞれが、同じ方向を向いた意思決定を自分で行うことができること と表現できよう。
故に、リーダーはその意思(Vision, Principle, Decision など)をドキュメントとして残さねばならない。
ミーティングが多すぎてドキュメントを書く時間がない？それはキャパオーバーの警報と捉える。ミーティングを減らすか残業するか、あるいはプロジェクトのオーナーシップをいくつか捨てよう。それくらいドキュメンテーションを大事にしよう。
ドキュメントの 2 分類#
これからドキュメント管理の指針について書く。
まずドキュメントの汎用的な分類を行う。
いろんな分類の方法があるだろうが、複雑だと運用できないので、あえてシンプルに以下の 2 つに絞る:
- Canonical Document
- Log
それぞれ以下のような性質を持つものとする:
| 観点 | Canonical Document | Log |
|---|---|---|
| 役割・目的 | 決定事項・背景の Single Source of Truth | 日々のやり取り・意思決定までの「足あと」 |
| 情報の寿命 | 長期保存（常に最新版に更新） | 短命（賞味期限は数時間〜数日） |
| メンテナンス | 定期的にリファクタ・追記・整理 | 基本的に メンテされない |
| 参照性 | 検索・リンクに強く「ここを見ればわかる」 | 流れ去りやすく「掘るコスト」が高い |
| コンテンツ例 | ADR, チームの Vision/Principle/Decision, PBI | 議事録, スレッドでの会話, 断片的なメモ |
| 主なツール例 | Notion ページ / GitHub Wiki / Confluence など | Slack チャンネル / チャットスレッド |
| 置き場所の容易さ | 明示的に “置く場所” を設計できる | 「置く」というより流れるので固定しにくい |
| 更新の単位 | “commit” や PR のように差分を記録 | スレッド単位で散発的に増殖 |
| トレーサビリティ | 変更履歴・リンクで 発端 → 決定 を遡れる | 会話が枝分かれし、全体像を把握しづらい |
| 読み手の負荷 | 必要なときに要点だけ読める | コンテクストをつかむのにログ全体を追う必要 |
| 作成コスト | 高い, 時間を費やしがち | 低い, 断片的に書ける |
平たく言えば、メンテナンスする覚悟を持った大事にしたい “正典” を Canonical Document として、それ以外の “メモ書き” を Log として扱う、ということ。
Log として断片的に書いたかけらを、まとめて Canonical Document に昇華する 、というのが基本的な運用。
ドキュメント管理の Tips#
ソフトウェア管理のアナロジー#
ドキュメント管理で大いに参照すべきはソフトウェア管理であろう。コードベースのマネジメントには、現在 Git ならびに Git/GitHub フローのような成熟した技法が存在する。実際、 GitLab は “docs as code” という言葉を使っている。
以下のような、ソフトウェア管理あるあるは、ドキュメント管理においてもおよそ当てはまる。これらの解決方法もまたソフトウェア管理のナレッジを借用できる。
| コード世界での概念 | 典型的な悩み・症状 | ドキュメント版に置き換えると | 防止・解消アクション |
|---|---|---|---|
| 技術的負債 (Technical Debt) | 仕様書より実装を優先し、後で修正コスト増 | ・「とりあえず Slack に書いたメモが正式仕様のまま」 ・古い手順書が現場で参照されバグ誘発 | 負債棚卸しスプリント を設け、更新所要時間 × 優先度で返済計画を立てる |
| コード腐敗 / ロット (Code Rot) | 時間が経つほど読めなくなる・ビルドが通らない | 用語のブレ・リンク切れ・参照先の消滅＝ドキュメント腐敗 | 30〜90 日で 自動リンクチェック & 用語リンター→ 失敗時にアラート |
| Big-Rewrite 病 | 「全部書き換えたい」→ 実装停止 | 大改訂で編集停止 → 情報空白期間 = ブラックアウト | 段階的リライト (Incremental Refactor) をルール化 |
| YAGNI (「要らん機能」) | 使われない抽象化 | 読まれない長文マニュアル = Dead Docs | ページビュー & フィードバックで 削除 or 圧縮 を判断 |
| リファクタ | 可読性・保守性向上 | 同義語統合、重複削除、章再構成 | スプリント末に Doc-Refactor Day を固定枠で確保 |
| コメント | 実装背景, Why の記述, 修正へのハードルを低減 | 主張の背景・Why を記述 | 書くときに常に意識する、あとでまとめて書こうと思わない(Tidy First) |
スクラムのアナロジー#
ドキュメントを書けないありがちな理由の一つに、書いたドキュメントうが他人に “読まれてしまう” ということがある。
他人に読まれるために書いているのだから当然なのだけど、書き手がつい恐れてしまうことの一つに、一度書いたドキュメントが独り歩きしてしまうことにある。
まさにデリダ的可撹乱性の問題であろう。テキストはしばしば書き手の意図を超えて読まれ、再解釈され、無限のコンテキストに折りたたまれてしまう。読者が思いも寄らない受け取り方をして混乱を招き、本来不要なコミュニケーションコストを払う状況に陥ることがある。この状況を極端に恐れるがあまり、可能な限り正確なドキュメントを書く欲求にかられ、それがドキュメントを書くコストを上げる羽目となり、結果的にドキュメントを書けなくなる。
この問題とどう向き合うか。
「タイトル先頭に WIP をつける」「テキストの中に書き手が迷っていることを率直に明記しておく」など細かなテクニックはあろうが、一番の解決策は 読者が勝手に解釈してしまうことがあることを受け入れる ことであろう。どんなに正確に書いたとしても、一定の確率で意図に反した伝わり方をしてしまうことがある、そんなもんである、と諦める。聖書や原始仏教からそうなんだから。
むしろ、ここにおけるリスクを避けるためにドキュメントを書かないよりも、不正確ながらもドキュメントを書いておくことのほうが得られる利益はずっと大きいと捉える。
このあたり、スクラムと考え方が似ている。 MVP に相当する Canonical Document を ship する。その後、フィードバックを受けて、それを元にドキュメントを更新していく。こう捉えると随分とドキュメントを書くハードルが低くなる。
AI の活用#
「 Log を Caonical Document に昇華する」行為は一般にしんどい。ルーマンは Zettelkasten と呼ばれる膨大な “メモ書き” をもとに、それを整理して多くの著作・論文を書いたとされるが、さらりと書いたこの「整理する」行為はそれほど簡単ではないはず。この整理のプロセスを愚直に実行し続けられるところにも、ルーマンの非凡さを見出すべきじゃないか。
整理のプロセスには、文法的に正しい文章を書くといったものから、断片的な Log をもとにどういう章立てでどういう順番でまとめるだとか、そういうものすべてが含まれる。
生成 AI はこの整理プロセスの補助に使える。 Andrew Ng のレクチャーの中でも、生成 AI の得意なことリストの中に「文章のフォーマッティング」が含まれている。この特性をより強化したものが DeepResearch と言えるかもしれない。ドキュメンテーションのコストを下げるためにうまく利用しよう。