4.6 文書化と知識の指標

概要と動機

本トピックは、コードベースを安全に維持するために必要な知識が、どこかに技術的に存在するというだけでなく、実際に文書化され見つけられる状態にあるかどうかを測定することで、第4部を締めくくります。トピック3.5は、開発者体験の関心事としてコミュニケーションと協働を扱いました。本トピックは、コードの側から同じ根底にある問題、知識の可用性を扱います。新しいエンジニア、あるいは不慣れなコードに取り組んでいる既存のエンジニアは、安全な変更を行うために必要なものを持っているでしょうか、それとも、その知識は縮小し続ける在籍年数の長い人々の頭の中だけに生きているでしょうか。

ここでの測定の課題は本物に難しく、本書の他のほとんどの指標よりも難しいものです。なぜなら、文書の品質と有用性は、カバレッジ率や複雑さのスコアよりも本質的に主観的だからです。本トピックのアプローチは、存在ではなく有用性の代理を測定することです。文書が実際にどれだけ頻繁にアクセスされるか、文書化された答えが存在するにもかかわらず同じ質問が繰り返しなされる頻度、そしてシステムに不慣れな人が生産的になるまでにどれだけの時間がかかるかです。これらの代理のどれも単独では完璧ではありませんが、一緒になると、コードベースが含むウィキページやREADMEファイルの数を数えるよりもはるかに正直な全体像を与えてくれます。

大規模なチームにとって、本トピックの懸念は、危機がその問題を強制するまで過小評価しやすい方法で、組織の在籍年数と離職と組み合わさります。同じ二人のエンジニアによって何年も維持されてきたシステムは、書かれた文書がほとんどなくても完璧にうまく機能することができますが、それはその二人のエンジニアが同じ年に両方とも去るまでのことで、その時点で組織は、その知識がどこにも永続的な形で実際には記録されていなかったことを発見します。スタートアップよりも一般的にシステムの寿命が長く、人員の継続性が不確実な企業や政府の組織は、このリスクをほとんどの組織よりも鋭く抱えています。

重要な原則

文書の存在は文書の有用性と同じではない。 それが実際に役立つかどうかを測定してください。単に存在するかどうかだけではありません。
文書化された答えが存在するにもかかわらず繰り返される質問は、発見可能性の問題を明らかにし、文書化の努力の問題ではない。 より多くのコンテンツが常に解決策であるとは限りません。
生産的な貢献までのオンボーディング時間は、強力で実用的な代理である。 全体的な知識の健全性のためで、トピック3.5の協働指標に直接つながります。
人々の頭の中だけに生きる知識は、現在どれだけうまく機能していても、安定した持続可能な状態ではなく、持続可能性のリスクである。
文書は劣化する。 1年前に正確だったページは、今では積極的に誤解を招くものになっているかもしれず、陳腐化そのものが追跡される必要があります。

推奨事項

単なる存在ではなく、文書のアクセスと陳腐化を追跡する

あなたの文書化プラットフォームがそれをサポートしている場合、ページが実際に閲覧される頻度を追跡し、別に、ページが最後に更新されてからの時間が、それが説明する基盤となるシステムがどれだけ頻繁に変更されたかと比較してどうかを追跡してください(トピック4.3のチャーンデータを相互参照することがここで直接役立ちます)。ページが最後に編集されてから本物に大きく変更されたシステムを説明しているページは、単に役に立たないだけでなく積極的に誤解を招くものである強力な候補であり、この陳腐化のシグナルは、文書が存在するかどうかを追跡することと少なくとも同じくらいの注意に値します。

発見可能性のシグナルとして繰り返される質問に注目する

文書化された答えがどこかに技術的に存在するにもかかわらず、同じ質問がチームのチャットチャンネルやオンボーディング中に繰り返しなされる場合、そのパターンは、答えが人々が自然に探す場所にないという発見可能性の問題を明らかにしており、より多くの執筆で解決される文書化の努力の問題ではありません。繰り返される質問を明示的に追跡し、それを使って、より多くのコンテンツを書くことよりも、既存のコンテンツを再編成したりより良く表示したりすることを優先してください。

最初の意味のある独立した貢献までのオンボーディング時間を測定する

トピック3.5で協働のシグナルとして紹介されたこの指標は、コードの側から見ても同様に文書化と知識の健全性のシグナルです。一貫して短く予測可能なオンボーディング時間は、本物にアクセス可能で正確な知識を示唆します。長く非常に変動の大きい時間、特に新しいチームメンバーをオンボーディングする特定の人物に大きく依存するものは、耐久性のある書かれた形ではなく個人の記憶に危険なほど集中した知識を示唆します。

文書化されていない重要な知識の領域を明示的に特定し優先順位づける

あなたの知識集中データ(トピック3.5のバス係数分析)を文書化のカバレッジと相互参照してください。バス係数が1で意味のある文書化がまったくないシステムは、同じ低いバス係数を持つが文書化がよくなされているシステムよりも優先的な注意に値する、深刻で複合的なリスクです。なぜなら、文書化は、専任の後継者が訓練される間、少なくとも部分的な緩和を提供するからです。

文書化の負債を技術的負債バックログ内の一つのカテゴリーとして扱う

文書化のギャップを別々に非公式に追跡するのではなく、特に重要でバス係数の低いシステムについて、重要な文書化のギャップを、トピック4.5で説明された同じ可視化され定量化されたバックログに組み込み、文書化の仕事が、コード中心の負債是正と比較して永続的に地位の低いタスクとして先送りされるのではなく、優先順位づけられた容量を公平に競争できるようにしてください。

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

アプローチ	長所	短所
文書化の測定なし	オーバーヘッドが低い	知識のリスクが危機によって発見が強制されるまで見えないままになる
文書の存在を数える(ページ数、README の有無)	単純で報告しやすい	有用性、正確さ、発見可能性について何も語らない
アクセスと陳腐化の追跡	実際の有用性と劣化を明らかにする	文書化プラットフォームの分析と継続的な見直しの規律が必要
代理としてのオンボーディング時間	実用的で具体的、本物のビジネスへの影響に直接つながる	間接的。文書化以外の要因もオンボーディング速度に影響する

中心にある緊張関係は測定可能性と意味です。文書の存在は自明に数えやすく、有用なことをほとんど何も教えてくれません。本物の有用性、人々が必要なときに文書化された知識を実際に見つけて頼ることができるかどうかは、実際に重要なことですが、直接測定するのがより難しいものです。この緊張を解消するには、本トピックが推奨する代理(アクセスパターン、チャーンと比較した陳腐化、繰り返される質問、オンボーディング時間)を組み合わせて使い、どれ一つとして完璧ではないが、それらの収束は存在数だけよりもはるかに意味があることを受け入れてください。

チームで話し合うべき問い

私たちの最も重要で最もバス係数の低いシステムについて、意味のある正確な文書が実際に存在するでしょうか、それとも去っていく専門家が本物の知識のほとんどを持ち去ってしまうでしょうか。これは本トピックの中心的な懸念の最も鋭く具体的な形です。まず私たちの単一の最もリスクの高いシステムについて正直に答えてください。
文書化された答えがどこかに存在するにもかかわらず、私たちのチームチャットで繰り返しなされる質問は何でしょうか。 一つをすぐに挙げられるなら、それは、より多くの執筆よりもおそらく既存のコンテンツの再編成やより良い表示によって、直接解決する価値のある発見可能性の問題です。
私たちの最も最近の新しいチームメンバーが最初の意味のある独立した貢献を行うまでにどれだけの時間がかかり、それはその前のチームメンバーと比べてどうだったでしょうか。個人間の大きく説明のつかないばらつきは、しばしば、耐久性のあるアクセス可能な文書ではなく、誰がたまたま誰かをオンボーディングするかに大きく依存する知識を指し示します。
私たちが最後に文書の一部がまだ正確かどうかを、それが書かれてから基盤となるシステムがどれだけ変化したかと比較して確認したのはいつでしょうか。正直な答えが「組織的にこれを確認していない」であるなら、その陳腐化のリスクは誰もが現在想定しているよりもおそらく大きいものです。
私たちの技術的負債バックログ(トピック4.5)は文書化のギャップを含んでいるでしょうか、それとも文書化の仕事はコードの修正と比較して永続的に地位の低いタスクとして先送りされているでしょうか。実際のバックログを確認し、文書化の負債が可視化され優先順位づけられた容量を競争しているか、それとも事実上見えなくなっているかを確認してください。
私たちの最も重要で最も文書化されていないシステムを理解している一人か二人の人物が同じ年に去った場合、私たちにどれだけのコストがかかるでしょうか。この具体的で不快な問いは、そのリスクを抽象的あるいはありそうにないものとして扱うのではなく、正直に答える価値があります。

業種別の視点

スタートアップ。 正式な文書化の指標は、知識が絶え間ない直接の会話を通じて広がる小さなチームでは通常不要です。注目すべきリスクは、トピック3.5が警告する同じバス係数の集中であり、今度は特に文書化に適用されます。チームが全員が毎日話す規模を超えて成長するにつれて、非公式にはうまく機能していた文書化されていない知識が本物の負債になります。

中小企業。 すべてにわたる包括的な文書化を試みるのではなく、まず私たちの単一の最も重要で最も冗長性のないシステムを、非公式であっても優先的に文書化してください。私たちの最もリスクの高い単一の障害点をカバーする短く正確な文書は、どこでも広くて浅いカバレッジよりも多くの本物の価値を提供します。

企業。 文書の陳腐化と発見可能性は両方ともここでうまくスケールしません。なぜなら、大規模な組織は、誰かがそれを最新に保つか一貫して整理し続けることができるよりも速く、多くのチームとプラットフォームにわたって文書を蓄積するからです。アクセスと陳腐化を規模で追跡するために文書化プラットフォームの分析に投資し、文書化の負債を組織全体の負債バックログの中で第一級のカテゴリーとして扱ってください。

政府。 公共部門の組織に共通する長い従業員の在籍年数は、見かけ上の安定性の背後に深刻な文書化されていない知識のリスクを隠すことがあります。なぜなら、同じ人物によって15年間維持されてきたシステムは、その人物が退職するまで完璧にうまく機能するかもしれないからです。文書化の健全性を、単なるエンジニアリング上の心地よさとしてではなく、人員と後継者計画に直接つながる業務継続性の懸念として明示的に扱ってください。

事例

企業。 ある金融サービス会社は、無関係な組織再編の最中に、中核的なリスク計算エンジンが、いくつかの古くなったコードのコメント以上の意味のある文書を持たず、それを最もよく理解している二人のエンジニアが同時に新しい取り組みに再配置されようとしていることを発見しました。大きな時間的プレッシャーの下で行われた緊急の文書化作業は、再配置が有効になる前に重要な知識を抽出し記録しましたが、その過程には数週間の専任のシニアエンジニアの時間がかかり、もし文書化の健全性が緊急事態として発見されるのではなく事前に積極的に追跡され優先順位づけられていたなら、より段階的に安く広げられたはずのものでした。

政府。 ある州政府の数十年前のケース管理システムは、長年にわたって相当な量の文書を蓄積していましたが、発見可能性の監査は、新しいチームメンバーが一貫して関連する既存の文書を見つけられず、実際には機関の広大で整理の行き届かない文書化プラットフォームのどこかにすでに答えられていた、同じ一握りの質問を繰り返しチームチャンネルで尋ねていることを発見しました。より多くのコンテンツを書く代わりに、機関は既存の文書の検索とナビゲーション構造の再編成と改善に投資し、フォローアップ調査は、一つの新しいコンテンツページも追加することなく、繰り返される質問の測定可能な減少と、新しいスタッフにとって有意に速く報告されたオンボーディング体験を示しました。

ビジネスケース:動機、ROI、総所有コスト

文書化の健全性を意図的に測定し管理することからの見返りは、回避された危機のコストです。上記の金融サービスの例は、積極的で段階的な知識の捕捉と、計画外のスタッフの移動によって強制された高価で圧縮された緊急事態との違いを示しています。文書化されていない重要な知識は、それが非常に高くつく瞬間までは見える形では何もコストがかからない、常在する負債です。

総所有コストは主に、本トピックが推奨する代理(アクセスパターン、陳腐化、繰り返される質問、オンボーディング時間)を追跡する規律と、文書化のギャップを、コード中心の仕事と比較して永続的に地位が低いものとして扱うのではなく、優先順位づけられたバックログに組み込む意欲です。その規律は、金融サービスの例が代替案として示す危機モードの知識抽出よりもはるかに安くつきます。

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

有用性ではなく文書の存在を数える。 知識が必要なときに実際にアクセス可能かどうかについてほとんど何も教えてくれません。
発見可能性を最初に確認せずに、繰り返される質問に応じてより多くのコンテンツを書く。 しばしばまったく間違った問題に対処します。
システムがどれだけ変化したかと比較して文書の陳腐化を一度も確認しない。 積極的に誤解を招く古くなったコンテンツのリスクを冒します。
文書化の負債をコードの負債と比較して永続的に地位が低いものとして扱う。 それをバックログ上で慢性的に優先度を下げられ見えないままにします。
見かけ上の安定性、何年も変化していないシステムを低リスクと誤認する。 単にまだ唯一の専門家を必要としたことがないシステムの背後に深刻な文書化されていないバス係数の問題を隠すことがあります。
緊急の人員の移行の間にのみ重要な文書化されていない知識を発見する。 これは本トピックが防ぐために組み立てられた高価で避けられる失敗モードです。

成熟度モデル

レベル1、開始: 文書化の健全性は測定されておらず、知識の集中と陳腐化のリスクは危機を通じてのみ発見されます。
レベル2、発展: いくつかの文書が存在しますが、アクセス、陳腐化、発見可能性の組織的な追跡はありません。
レベル3、標準化: 重要なシステムについてアクセスと陳腐化が追跡され、オンボーディング時間が組織全体で知識の健全性の代理として測定されています。
レベル4、管理: 文書化のギャップは優先順位づけられた技術的負債バックログに組み込まれ、最も深刻な複合リスクを特定するためにバス係数のリスクと相互参照されています。
レベル5、最適化: 組織は、人員の移行がその問題を強制する前に積極的に文書化されていない重要な知識のリスクを特定し対処し、文書化への投資にたどれる具体的で測定可能なオンボーディングやインシデント対応の改善を指し示すことができます。

議論のためのアイデア

今、私たちの最も深刻な低いバス係数と不十分な文書化の組み合わせは何でしょうか。
文書化された答えが存在するにもかかわらず繰り返しなされる質問は何でしょうか。
重要な文書の一部が陳腐化して誤解を招くものになったことをどうすれば知ることができるでしょうか。
私たちの技術的負債バックログは文書化のギャップを含んでいるでしょうか、それとも見えないままでしょうか。
私たちの最も文書化されていないシステムの唯一の専門家が今年去った場合、私たちにどれだけのコストがかかるでしょうか。

主な要点

存在ではなく有用性を測定してください。文書が実際に役立つかどうかを、アクセスパターン、陳腐化、繰り返される質問などの代理を使って測定します。
文書化された答えが存在するにもかかわらず繰り返される質問は、必ずしもコンテンツ努力の問題ではなく、発見可能性の問題を明らかにします。
生産的な貢献までのオンボーディング時間は、全体的な知識の健全性の強力で実用的な代理です。
文書化されていない重要な知識は複合的なリスクである。 特に低いバス係数(トピック3.5)と組み合わさると、見える形で何もコストがかからないが、一度にまとめて多くのコストがかかります。
文書化のギャップを技術的負債バックログ(トピック4.5)に組み込んで、優先順位づけられた容量を公平に競争できるようにしてください。

参考文献とさらなる読書

Docs for Developers: An Engineer’s Field Guide to Technical Writing, Jared Bhatti、Zachariah Goldberg、Ted Kubaska、Sarah Moir 著。
A Philosophy of Software Design, John Ousterhout 著。
Team Topologies, Matthew Skelton、Manuel Pais 著。
Accelerate: The Science of Lean Software and DevOps, Nicole Forsgren、Jez Humble、Gene Kim 著。