過去15年間、私は数十件のソフトウェアプロジェクトに取り組んできたが、ドキュメンタリーがひどかったのはほぼ毎回である。 開発者は、すでにすべてを理解していると思っているので、ドキュメントの必要性を過小評価します。 マネージャーは、開発者が単純にコードを読み、数時間でプロジェクトを理解できることを仮定しているため、それを過小評価します。 人々がドキュメントを過小評価しない場合でも、そのための時間と能力はしばしば欠けています。正確で最新の概要は、すでに多くの責任を負っている上級開発者の頭に座っています。 何が文書化されなければならないか、何が明らかであるかについての共通の文化や直感は存在しません。開発者はしばしば微妙な機能のコメントを追加したり、より明確な変数名やタイプが問題を解決した場合のパラメータを記述したりします。 文書が時代遅れなのかもしれない。 たった 多くのチームが文書を「任意の手続き」として扱うことを示す。 企業の4%は常にプロセスをドキュメンタリー化 https://www.bptrends.com/bpt/wp-content/uploads/2015-BPT-Survey-Report.pdf/ 同時に、良い文書がなければ、ビジネスは膨大な時間とお金を失うという強力な証拠があります。 「不十分なドキュメント」は、開発者の41%が無駄な時間の主な原因とし、開発者の69%が週に8時間以上を無駄にしている(1000人の開発者あたり年間生産性の損失は約1850万ドル) https://newsletter.getdx.com/p/state-of-developer-experience-2024 新しいエンジニアのオンボードは3〜9ヶ月かかります、ドキュメントに大きく依存します https://stripe.com/files/reports/the-developer-coefficient.pdf ドキュメンタリーの欠如は、技術的な負債の主要な要素です(https://www.informit.com/store/economics-of-software-quality-9780132582209) 30人以上のプログラマーを対象とした実験では、ドキュメントの欠如により、メンテナンスタスク中にコードを理解する時間を21%増やすことが示されました。 では、このような広範囲にわたる文書の欠如の背後にある実際の障壁は何なのでしょうか。 Andrew Forwardの「ソフトウェア文書化 - コミュニケーションの芸術を構築し維持する」という素晴らしい作品では、実際の理由をよく調べています。 External Factors Influencing Documentation Quality あなたが見ることができるように、時間と予算の欠如は、ドキュメンタリーの努力が役に立たず、急速に時代遅れになってしまうという挫折と関連しています。 したがって、手動の努力を減らし、文書が時代遅れになる問題を解決すれば、重要な一歩を踏み出すことができます。 開発者コミュニティはすでにJavadocや類似のツールのようなアプローチを導入し、コード署名からドキュメントを自動的に生成しています。 したがって、我々は依然として、きちんと書かれた、最新の、人間が読める文書を必要としている。 本当の課題は、ドキュメンタリーが一度に配信されるものではなく、 チームが最初から良いドキュメントを書いているとしても、コードはドキュメントの習慣よりも速く進化します。 生きるアーティスト つまり、ボトルネックは、 ドキュメンタリーですが、 . 書く 正しく保つ ソリューション AI AIは実際には、コードとドキュメントの間のシンプルなパターンを適合するのに優れています. There are some nice solutions where you can automate documentation drift via AI: Merge request rules, pointing agent to existing documentation and changed code base Claude Code documentation agent that keeps project docs up to date with Docusaurus. npx claude-code-templates@latest --agent=documentation/docusaurus-expert --yes このアプローチは、うまく機能します: 高レベルの記述の更新 コードの意図の概要 古いフレーズの書き換え 失われた文脈の復元 しかし、AIには明確な限界があります: それは構造的不一致(例えば、文書化されていない env vars、ポート、CLIの旗、機能の旗)を検出するために苦労します。 これは、ドキュメントが不完全または曖昧である場合に特に幻覚を起こす可能性があります。 それは追跡可能な、決定的なチェックを生成しません - それぞれの走行は少し異なる結果を生成することができます。 ドメイン知識がなければ、何が重要か、何が騒音かを確実に言えることはできません。 つまり、AIは助けることができる。 しかし、まだ信頼性はなく、A . rewrite and improve text source of truth validator STATIC CHECK ツール like ドキュメントを継続的に監視する必要があるものとして扱うことで、コードの品質やインフラストラクチャのドライブと同じように、この問題を解決します. それは純粋にアルゴリズム的に動作しますので、幻覚に影響されません。 ドック Ducku は、環境変数、API ルート、サービス入力ポイント、モジュールインポート、ディレクトリ構造、構成キーから構造信号を抽出し、READMEs と wiki で参照されているものと比較することで機能します。 現在の能力 Entity presence checking: 環境変数、構成キー、ポート、API ルート、またはスクリプト名が文書に表示される場合を検出しますが、コード(およびその逆)に表示されません。 Parallel entity coverage: Identifies groups of similar items (services, ETL jobs, lambda handlers, CLI commands) and flags undocumented additions. 同様の項目のグループ(サービス、ETL jobs、Lambda handlers、CLIコマンド)を識別します。 デッドモジュール分析:説明に値する入力点または時代遅れの文物のいずれかで、どこにも輸入/使用されていないファイルを検出します。 URL 整合性チェック:内部または外部リソースへの破損または時代遅れのリンクを検出します。 魔法とスタイルの一貫性:通常無視される基本的な衛生。 これはすでに、実際のプロジェクトにおける静かなドキュメンタリーのドライブの大部分を減らすのに十分です。 結論 ドキュメンタリーは、エンジニアが無関心だから失敗しない。 コードにはテストがあり、インフラストラクチャにはドライブ検出があり、CIにはポリシーゲートがあり、ドキュメントにはほとんどのチームでは何もない。 no feedback loop AIは表現を改善し、文脈を復元することができますが、ドキュメントが正しいかどうかを信頼できることはできません。 一方、静的チェックは事実的な調和を検証することができるが、意図や領域論理を説明することはできない。 correct 両方とも、あなたが必要とするものを手に入れることができます。
