2.7 ドキュメント

概要と動機

ドキュメントとは、人々がコードだけから理解を組み立てることなく、ソフトウェアを使い、運用し、変更できるようにする、書かれた知識です。さまざまなジャンルがあります。始め方、タスクの達成の仕方、システムの構造、インシデントへの対応の仕方、APIが何を受け取り何を返すか。それぞれが、異なるニーズを持つ異なる読み手に仕えます。良いドキュメントは任意ではありません。大きな組織全体にスケールする知識と、ほんの数人の頭の中にしかない知識との違いです。

大きなチームにとって、ドキュメントは、特定の人物への依存のリスク(重要な知識が一人か数人にしかない危険)に対する最良の防御であり、新参者を最も速くオンボードする方法です。何百人ものエンジニアが、自分たちが作っていないシステムに依存し、人々が絶えず加わり、異動し、去るとき、知識が書き留められ、見つけやすい場合にのみ、組織は機能できます。文書化されていないシステムは脆くなります。作者だけが安全に変更でき、その作者が去ると、組織は自らのソフトウェアを保守する能力を失います。これは、規模における最も一般的で高価な失敗の一つです。

企業や政府の文脈では、賭け金はさらに上がります。システムは長く生きるので、ドキュメントは、元のチームがいなくなって何年も、何十年も後の保守担当者に仕えなければなりません。規制や監査の制度は、しばしば統制の証拠として特定の文書を義務づけます。アーキテクチャの記録、ランブック(段階的な運用とインシデント対応の手順)、決定ログ。ベンダー間で引き継がれる公共部門のシステムは、契約の境界を越えて知識を運ぶために、完全にドキュメントに頼ります。それでもドキュメントは腐りやすいことで有名なので、本当の課題は、ソフトウェアが変わる中でそれを正確に保つことです。

主要原則

特定のニーズを持つ特定の読み手のために書きます。異なる種類のドキュメントは、異なる目的に仕えます。
ドキュメントをコードの近くに置き、コードとして扱います(docs-as-code)。
正確さは網羅性に勝ります。信頼できる少量のドキュメントは、間違った大量のドキュメントに勝ります。
生成できるものは生成します。ツールが信頼できる唯一の情報源から作れるものを、手作業で保守してはいけません。
ドキュメントの腐敗に積極的に対抗します。古いドキュメントは誤解させるので、ないよりも悪いです。
ドキュメントを見つけやすくします。見つけられない知識は、事実上存在しません。
現在の状態だけでなく、決定とその根拠を記録します。

推奨事項

docs-as-codeを採用する

ドキュメントを、それが記述するコードのすぐ隣のバージョン管理に置き、プレーンテキストのマークアップで書き、同じプルリクエストのプロセスでレビューします。これでバージョン管理され、レビュー可能で、コードの近くにあり、両方を一緒に更新できます。自動化されたパイプラインで公開し、最新版がいつでも利用できるようにします。ドキュメントをコードとして扱うことは、コードを信頼できるものに保つ同じ規律をもたらします。レビュー、履歴、自動化です。

Diátaxisフレームワークで内容を構造化する

ドキュメントを四つの異なる種類に整理します。混ぜるとどの読み手にもうまく仕えないからです。チュートリアル(学習指向、新参者向け)、ハウツーガイド(タスク指向、特定の目標のため)、リファレンス(情報指向、正確で完全)、解説(理解指向、なぜと文脈)。これらを分けておくと、各ページに明確な一つの役割と一つの読み手ができるので、あらゆることが書きやすく、たどりやすく、保守しやすくなります。

不可欠な運用ドキュメントを維持する

すべてのリポジトリに、玄関口として明確なREADMEを与えます。それが何か、どうビルドして動かすか、次にどこへ行くか。運用タスクとインシデント対応のためのランブックを書き、専門家だけでなく、オンコールの誰もが行動できるようにします。システムの構造と主要なコンポーネントを説明するアーキテクチャのドキュメントを保ちます。そして、新しいエンジニアをすぐに生産的にするオンボーディングのドキュメントを提供します。これらは、ないときに最も惜しまれる文書です。

APIドキュメントと変更履歴を信頼できる唯一の情報源から生成する

APIのリファレンスドキュメントを、機械可読な契約やコードの注釈から生成し、実際のインターフェースから乖離できないようにします。変更履歴を保ち、理想的には構造化されたコミットやリリースノートから生成して、利用者がバージョン間で何が変わったかを見られるようにします。これらを自動化することで、最も腐りやすい手作業で保守するドキュメントがあなたの手を離れ、信頼できる状態に保たれます。

アーキテクチャの決定を記録する

重要なアーキテクチャと設計の決定を、文脈、決定、その帰結を述べる、日付付きの軽い記録として残します。これらの決定記録は、そうでなければ失われる根拠を保存するので、将来の保守担当者は、システムがなぜそうなっているかを、疑い直したり古い間違いを繰り返したりする代わりに、見ることができます。企業や政府のシステムの長い寿命にわたって、特に見返りがあります。

ドキュメントの腐敗に意図して対抗する

古いドキュメントを欠陥として扱います。振る舞いを変える同じ変更の一部としてドキュメントを更新し、それをレビューの期待にします。所有者を割り当て、すべての重要な文書に責任者がいるようにします。価値の高いドキュメントを折に触れて正確さについてレビューし、時代遅れのものを刈り込み、もう信頼できないものは取り除くか明確に印を付けます。最も腐りにくいドキュメントは、生きたドキュメント、つまりシステム自体に対して生成またはテストされるものです。

ナレッジマネジメントと見つけやすさに投資する

良い検索、明確なナビゲーション、既知の置き場所を通じてドキュメントを見つけやすくし、人々が誰かに尋ねなくても必要なものを見つけられるようにします。あまりに多くの分断されたウィキとツールに散らばらせてはいけません。そして、チャットのスレッドや人々の頭の中にある非公式な理解である暗黙知を、失われる前に、持続的で見つけやすい形に取り込みます。

トレードオフ: 長所と短所

アプローチ	長所	短所
docs-as-code	バージョン管理され、レビュー可能で、コードに近い。腐敗が少ない	エンジニアの規律が必要。技術者でない書き手にはやさしくない
ウィキ / ナレッジベース	編集が簡単。誰でもアクセスできる	コードから乖離する。分断する。静かに腐る
生成されたドキュメント(API、変更履歴)	常に正確。保守が少ない	情報源が表現するものに限られる。ツールが必要
手書きの解説	機械には作れない豊かな文脈と根拠	労力がかかる。古くなりやすい
Diátaxisの構造	ページごとに明確な目的。たどりやすく保守しやすい	前もっての構造化の労力。書き手の規律が必要

中心的なトレードオフは、労力と、正確さおよび耐久性の間にあります。書くのが最も安いドキュメント、つまり急いで書いたウィキのページは、最も腐りやすく分断されやすいものでもあります。最も耐久性のあるドキュメント、つまり情報源から生成されるか、コードとしてレビューされるものは、前もってより多くの規律を要しますが、信頼できる状態を保ちます。良い経験則があります。生成できるものは生成し、残りはコードの近くに置いてコードのようにレビューし、労力のかかる手書きの解説は、人間にしか提供できない根拠のために取っておきます。

チームで議論すべき問い

ドキュメントは読み手のニーズで分けられていますか。それとも、チュートリアル、リファレンス、解説が一つのページにごちゃ混ぜになっていますか。本章は、チュートリアル、ハウツーガイド、リファレンス、解説へのDiátaxisの分割を推奨し、種類を混ぜることを、どの読み手にもうまく仕えないアンチパターンとして挙げています。規模が大きくなると、システムを学ぶ新参者と、正確な事実を探すオンコールのエンジニアは、異なるページを必要とし、混ざった一つのページは両方を遅くします。シグナルを持ち込んでください。最もよく訪れられるドキュメントを選び、それぞれが明確な一つの役割と一つの読み手を持っているか確認します。最悪のものを別々の種類に再構成し、各ページが書きやすく、たどりやすく、最新に保ちやすくなるようにします。その構造が、組織が成長するにつれてドキュメントを保守可能にするものです。
重要なアーキテクチャの決定を、根拠とともに記録していますか。それとも現在の状態だけですか。 本章は、文脈、決定、帰結を述べる、軽く日付付きの決定記録を推奨し、企業や政府のシステムの長い寿命にわたって最も見返りがあると指摘しています。それがなければ、何年も後の保守担当者は、システムがなぜそうなのかを見られず、妥当な選択を疑い直したり、古い間違いを繰り返したりします。具体的なシグナルとして、その理由が今はチャットのスレッドや誰かの記憶にしかない、最近の難しい決定を持ち込んでください。短い決定記録の形式を採用し、重要な設計変更のたびに一つ書くことを組み込みます。根拠は、人間にしか提供できず、書かれなければ最も速く腐る知識そのものです。
オンコールのエンジニアは誰でも、システムを作った人を呼び出さずに、ランブックだけでインシデントに対応できますか。 本章はランブックを、専門家だけでなくオンコールの誰もが行動できるようにするための不可欠な運用ドキュメントと名指しし、ランブックが契約の境界を越えて知識を運んだからこそシステムを引き継げた政府のチームを描いています。特定の人物への依存のリスクがこれが防ぐ失敗です。唯一の専門家に連絡がつかない、あるいはいなくなったとき、文書化されていない復旧手順は、日常的なインシデントを障害に変えます。証拠を持ち込んでください。最近のインシデントを取り上げ、ランブックだけでそれが解決できたかを確認します。人々が恐れる手順のランブックを書いてテストし、単独では成り立たないランブックを欠陥として扱います。それが、午前2時の復旧と、午前2時のエスカレーションの違いです。
どのAPIリファレンスと変更履歴が信頼できる唯一の情報源から生成されていて、どれがまだ手作業で保守され、静かに乖離していますか。 本章は、リファレンスドキュメントを機械可読な契約やコードの注釈から生成して、実際のインターフェースから乖離できないようにするよう述べ、生成可能な内容を手作業で保守することをアンチパターンとして挙げています。大きなチームでは、実際のインターフェースに遅れる手書きのAPIドキュメントは、ないよりも悪いものです。それを信頼するすべての利用者が壊れた統合を書き、失敗は、それを引き起こした古いページから遠く離れた所に現れます。具体的なシグナルを持ち込んでください。最もよく使われるインターフェースを数個サンプルし、公開されたリファレンスを実際の契約と比較して、それぞれがどれだけ乖離したかを確認します。乖離を見つけたら、リファレンスをビルドに組み込んで変更のたびに再生成し、手で保守するコピーを退役させます。インターフェースが、見えないチーム、ベンダー、契約の境界を越えて利用される企業や政府の設定では、権威ある生成されたリファレンスが、統合担当者が虚構に対して作るのを防ぐ唯一のものであることがよくあります。
価値の高いドキュメントはそれぞれ誰が所有し、今日、一つが古くなったことにどうやって気づきますか。 本章は古いドキュメントを欠陥として扱い、所有者のいない文書は、更新が誰の仕事でもないために腐ること、現在のものとして示された古いドキュメントは、すべてのドキュメントへの信頼を破壊することを警告しています。規模が大きくなると、危険は単一の間違ったページではなく、信頼がゆっくり浸食されることです。読み手が古い手順で痛い目に遭うと、全体を信頼するのをやめ、人々を中断することに戻ります。最も重要なドキュメントの所有者のマップと、腐敗がどう検出されるか(レビューの周期、生成、システムに対するテスト、あるいは単なる運)についての誠実な答えを持ち込んでください。重要なあらゆる文書に名前のある所有者を割り当て、生成またはテストされる生きたドキュメントを好み、古さが、恥をかいた読み手を通じてではなく機械的に現れるようにします。元のチームより長生きする企業や政府のシステムでは、所有者のいないドキュメントは、監査人や引き継ぐベンダーが、いずれ請求してくる負債です。
ドキュメントはどれだけ見つけやすく、どれだけの重要な知識が、まだチャットのスレッドや人々の頭の中にだけありますか。 本章は、見つけられない知識は事実上存在しないと述べ、ドキュメントをあまりに多くの分断されたウィキとツールに散らばらせることを警告し、暗黙知を、失われる前に持続的で見つけやすい形に取り込むよう促しています。大きな組織では、同じ事実が、すでにどこに書かれたか誰も見つけられないために、何度も再発見され、再質問され、再回答され、すべての退職が、かけがえのない文脈を持ち去ります。証拠を持ち込んでください。保守している別々のドキュメントの置き場所の数を数え、重要な事実三つを検索だけで見つけてみて、本当の答えが誰かの記憶や埋もれたメッセージにあったのはどこかを記録します。本物の検索と明確なナビゲーションを備えた既知の置き場所に統合し、暗黙知の取り込みを、英雄的な救出ではなく、仕事の日常的な一部にします。システムが契約によってベンダーやチームの間で引き継がれる、公共部門や外部委託の多い文脈では、見つけやすい書かれた知識だけが、引き継ぎを生き延びます。

セクター別の視点

スタートアップ。 少数のエンジニアで余裕のあるランウェイもないので、午前2時の障害や新規採用者が実際に必要とするものだけを文書化してください。サービスごとの本物のREADME、皆が恐れるデプロイと復旧の手順についてのテスト済みのランブックを一つ、そして他では忘れてしまう決定についての日付付きの短いメモ。APIドキュメントは契約から生成し、手で保守しないようにします。ドキュメントのプラットフォームを構築するのは控えてください。本物の痛みを感じるまでは、コードの隣のバージョン管理されたマークアップのフォルダで十分です。

小規模事業者。 テクニカルライターはおらず予算も厳しいので、人員配置のあるプログラムではなく、ツールがすでに生成するドキュメントと、軽いdocs-as-codeに頼ってください。選択を買うか作るかとして枠づけます。手作業で手入れしなければならないウィキより、自ら最新のリファレンスと検索可能なナレッジベースを生成するプラットフォームを好みます。乏しい労力を、なければ事業が止まる二、三の文書に使い、間違った、あるいは欠けたページを、所有権を直すきっかけにします。

大企業。 多くのチームにわたって、問題は一貫性と見つけやすさです。共有のdocs-as-codeのパイプライン、Diátaxisのような共通の構造、生成されたAPIリファレンスと変更履歴、そして知識が数十のウィキに分断されないよう、どこでも同じように適用される決定記録。価値の高いあらゆる文書に所有権を割り当て、存在だけでなく正確さを測定します。アーキテクチャの記録、ランブック、決定ログを監査の証拠として扱い、その作り方を標準化して、統制のレビューが、慌ただしさではなく、文書化された説明可能な跡を見つけられるようにします。

政府。 調達規則と公的な説明責任は、ドキュメントを好意ではなく成果物にします。アーキテクチャのドキュメント、ランブック、決定記録を、義務づけられた成果物として契約に書き込み、ベンダーの移行を越えて知識が生き延び、システムが引き継ぐ誰にでも運用できるよう、正確さについてレビューします。承認されたオペレーターなら誰でもランブックだけでインシデントに対応できることを求め、選択がなぜ行われたかの透明な公的記録として、決定ログを保ちます。ここでドキュメントが薄いことは、私的な不便ではありません。納税者が資金を出す、高価なリバースエンジニアリングになります。

事例

スタートアップ。 5人のスタートアップは、サービスごとに本物のREADMEを書き、皆が恐れるデプロイと復旧の手順について短いランブックを書くので、午前2時の障害が、システムを知っている唯一の創業者を起こすことに依存しません。APIドキュメントは手で書く代わりに契約から生成し、データベースと認証のアプローチをなぜ選んだかを説明する日付付きのメモをいくつか書き留めます。軽いままですが、六人目と七人目の採用者が、全員を中断するのではなく、ドキュメントからオンボードできることを意味します。

大企業。 大手のソフトウェア会社は、すべてのドキュメントをコードと同じリポジトリに置き、マークアップで書き、記述する変更のすぐ隣でプルリクエストでレビューします。APIリファレンスはサービスの契約から生成されるので、乖離しません。変更履歴は構造化されたコミットから生成され、アーキテクチャ決定記録は主要な選択の背後にある推論を保存します。公開されたドキュメントサイトは、マージのたびに自動的にビルドされます。オンボーディングガイドとランブックが最新で見つけやすいので、新しいエンジニアは速く生産的になり、オンコールのエンジニアは元の作者を呼び出す代わりにランブックに頼ります。

政府。 国の機関が、去っていく契約者からシステムを引き継ぎ、契約の境界を越えて知識を運ぶために、完全にドキュメントに頼ります。前のベンダーが、アーキテクチャのドキュメント、ランブック、決定記録を義務づけられた成果物として維持していたので、新しいチームは、元の作者なしにシステムを運用し変更できます。ドキュメントが薄かった所では、機関は高価なリバースエンジニアリングに直面します。その経験が新しい方針を促します。ドキュメントは、後回しではなく、正確さについてレビューされる契約上の成果物であり、ランブックは、承認されたオペレーターなら誰でもインシデントに対応できるものでなければなりません。

ビジネスケース: 動機、ROI、TCO

ドキュメントは、より短いオンボーディング時間、より少ない特定の人物への依存のリスク、より速いインシデント対応、そしてシステムの寿命にわたるより低い変更コストで元を取ります。新しいエンジニアが数週間ではなく数日で生産性に達する、オンコールの担当者がエスカレーションする代わりにランブックでインシデントを解決する、保守担当者がシステムが作られて何年も後に自信を持って変更する。これらは、大きな組織と長いシステムの寿命にわたって複利で積み重なる、大きく繰り返し発生する節約です。

ドキュメントのコストは何でしょうか。執筆と保守の労力です。ドキュメントを書かないことのコストは何でしょうか。継続的に支払います。遅いオンボーディング、繰り返される質問、特定の人物がボトルネックになること、遅いインシデント復旧、そして極端な場合には、誰も安全に変更できないシステムが、高価な書き直しやリバースエンジニアリングを強いること。ベンダーの移行や監査の場面では、欠けたドキュメントは直接的な契約上とコンプライアンス上のコストを負いえます。リーダーシップに論拠を示すには、オンボーディング時間、インシデント対応時間、そして重要な知識のどれだけが個々人の頭にあるかに数字を付けてください。それから、docs-as-codeと生成を、それに見合う保守の負担なしに持続的なドキュメントを得る方法として枠づけます。そして、不正確なドキュメントは負債であり、投資にはそれを最新に保つことが含まれなければならないと強調します。

アンチパターンと落とし穴

現在のものとして示される古いドキュメント: 読み手を誤解させ、すべてのドキュメントへの信頼を破壊すること。
書いたら終わりのウィキ: 作られて決して更新されず、現実から静かに乖離していくページ。
ドキュメントの分断: 知識が多くのツールとウィキに散らばり、何も見つけられないこと。
ドキュメントの種類の混在: チュートリアル、リファレンス、解説が一つのページにごちゃ混ぜになり、どの読み手にも仕えないこと。
生成可能な内容の手作業での保守: 実際のインターフェースから必ず乖離する、手書きのAPIドキュメント。
属人的な知識: 重要な理解が人々の頭とチャットの履歴にだけあり、彼らが去ると失われること。
後回しのドキュメント: 変更と並行してではなく、最後に、書かれるとしても、書かれること。
所有者がいない: 責任者のいないドキュメントは、更新が誰の仕事でもないために腐ること。

成熟度モデル

レベル1、開始。 ドキュメントはまばらで、散らばり、古く、知識は人々の頭の中にあります。存在するものは一度書かれて二度と触れられておらず、障害や退職は、システムをリバースエンジニアリングすることを意味します。
レベル2、発展。 READMEや少数のランブックのような重要な文書は存在しますが、保守は一貫せず、見つけにくいものです。うまく文書化するチームもあれば、ほとんどしないチームもあり、リポジトリが何を持つべきか、どこに置くべきかについての共有の期待はありません。
レベル3、標準化。 docs-as-codeが組織全体の標準です。Diátaxisのような共通の構造、生成されたAPIリファレンスと変更履歴、決定記録、そしてドキュメントが、記述するコードとともに変わるというレビューでの期待。価値の高いすべての文書に名前のある所有者がおり、本物の検索を備えた既知の置き場所が一つあります。
レベル4、管理。 ドキュメントは、存在するだけでなく測定されます。不可欠な文書のカバレッジ、コード変更率に対するドキュメント変更率、オンボーディング時間、ランブックだけでのインシデント解決、定義された古さの閾値に対する鮮度を追跡し、それらの指標をベースラインに対してレビューします。腐敗は、生成、システムに対するテスト、リンクと正確さのチェックを通じて機械的に捉えられ、古いページは、偶然ではなく証拠に基づいて印を付けられるか刈り込まれます。
レベル5、オーケストレーション。 ドキュメントは継続的に改善され、組織全体に統合されています。生きていて、大部分が生成されるかシステムに対してテストされ、所有され、見つけやすく、適応的です。指標が投資先にフィードバックされ、暗黙知の取り込みは仕事の日常的な一部で、コーパスはシステム、チーム、読み手の変化に応じて積極的に再均衡され刈り込まれます。

議論のためのアイデア

明日消えたら組織に最も痛手となるドキュメントはどれで、それは現在存在し、最新のままですか。
ドキュメントの更新を、別の雑務ではなく、コードを変更することの自然な一部にするには、どうしますか。
手書きのドキュメントを、信頼できる唯一の情報源に結びついた生成されたドキュメントに置き換えられるのはどこですか。
ドキュメントが存在するだけでなく、正確で使われていることを、どう測定しますか。
AIアシスタントは、ドキュメントの書き方、保守、検索をどう変えるべきで、もっともらしいが間違った内容を持ち込みうるのはどこですか。
暗黙知を持つ人々が去る前に、それをどう取り込みますか。

要点

ドキュメントをコードとして扱います。バージョン管理され、レビューされ、情報源の近くにあり、自動的に公開されます。
チュートリアル、ハウツーガイド、リファレンス、解説で、読み手のニーズによって内容を構造化します。
価値の高い不可欠なもの、READMEs、ランブック、アーキテクチャのドキュメント、オンボーディング、決定記録を維持します。
APIドキュメントと変更履歴を生成し、信頼できる唯一の情報源から乖離できないようにします。
所有権、レビューの期待、刈り込みで腐敗に対抗します。不正確なドキュメントは、ないよりも悪いものです。

参考文献とさらなる読み物

Daniele Procida, Diátaxis documentation framework
Andrew Etter, Modern Technical Writing
Anne Gentle, Docs Like Code
Google, Developer Documentation Style Guide and Season of Docs guidance (as reference exemplars)
Michael Nygard, Documenting Architecture Decisions (architecture decision records)
Andrew Hunt and David Thomas, The Pragmatic Programmer (on knowledge and documentation)
Keep a Changelog (as a reference convention)