ドキュメントが自動的に作成されるとしたらどうでしょうか？

「自己執筆型ドキュメント（自己生成ドキュメント）」と聞くと、矛盾しているように思えるかもしれません。ドキュメント作成とは、人間が行うべき活動、つまりエンジニアが何かを理解し、腰を据えて、文章で説明するものだと考えられているからです。ドキュメントが勝手に作成されるというアイデアは、品質がひどいものになる（AIが生成した中身のないコンテンツ）か、実用に耐えないほど表面的なもの（誰も読まない自動生成のREADME）になるかのどちらかを予感させます。

しかし、実際の運用において自己執筆型ドキュメントが意味するものは、そのどちらでもありません。

実際の仕組み

その前提として、優れた技術ドキュメントを作成するために必要な知識は、すでに存在しています。それは、エンジニアが何をなぜ変更したかを説明するPR（プルリクエスト）の説明の中にあります。チームがアーキテクチャの決定について議論し、トレードオフを検討し、設計上の疑問を解決するSlackの会話の中にあります。優先順位を設定し、移行を計画し、インシデントを検証するミーティングの録画の中にあります。さらには、コミットメッセージや、設計書、コードレビューのコメントの中にも存在しています。

これらの知識は、現在、一時的なものにとどまっています。Slackのスレッドは数日も経てば画面から消え去ります。PRはマージされて忘れ去られます。ミーティングの録画は、誰も見返さないフォルダーに眠ったままになります。知識は、通常の1週間の業務の中で作成され、共有され、そして失われているのです。

自己執筆型ドキュメントは、この知識が作成されると同時にキャプチャし、ベースとなる活動の変化に合わせて常に最新状態に保たれる、永続的で検索可能なWikiへと構造化します。

そのプロセスは以下の通りです：

ソースを接続する。 GitHubのリポジトリ、Slackのチャンネル、ミーティングの録画、Discordのサーバーなど。これらは、エンジニアリングの知識がすでに共有されている場所です。

システムが読み取り、統合する。 新しいPRがマージされ、新しい会話が行われ、新しいミーティングが録画されると、システムはそのコンテンツを処理し、エンジニアリングに関連する知識を抽出して、構造化されたドキュメントに統合します。

Wikiが自動で維持される。 PRによってシステムの動作が変更されると、そのシステムに関するドキュメントが更新されます。Slackの会話で設計上の疑問が解決されると、関連するドキュメントにその決定が反映されます。ドキュメントが最新に保たれるのは、ベースとなるシステムを変更する活動そのものからドキュメントが生成されるためです。

エンジニアがレビューし、ブラッシュアップする。 システムが最初のドラフトを作成します。エンジニアはそれをレビューし、不正確な点を修正し、コンテキストを追加し、自動化システムでは推測できなかった洞察を加えてドキュメントをより豊かなものにします。エンジニアの役割は「執筆者」から「編集者」へと移行し、これは2時間の執筆セッションではなく、10分のタスクで済みます。

どのようなアウトプットになるか

生成されたドキュメントは、構造化され、引用元が明記され、編集可能です。

「構造化されている」とは、システム概要、APIドキュメント、決定記録（ADR）、変更履歴、チーム専用のWikiなど、一貫したフォーマットに従っていることを意味します。フォーマットが標準化されているため、どのシステムを説明しているかに関わらず、ドキュメントの閲覧や予測が容易になります。

「引用元が明記されている」とは、ドキュメント内のすべての記述が、その情報源（PR、Slackのメッセージ、ミーティングのタイムスタンプなど）にリンクしていることを意味します。ドキュメントを読むエンジニアは、リンクをクリックして元のコンテキストにアクセスし、記述内容を検証したり、詳細な情報を得たりすることができます。これこそが、自己執筆型ドキュメントと通常のAI生成テキストとの違いです。ドキュメントはモデルの学習データから生成されるのではなく、実際の活動に基づいているのです。

「編集可能」とは、生成されたドキュメントが最終成果物ではなく、出発点であることを意味します。エンジニアはドキュメントを変更、再構成、注釈付けできます。システムはこれらの編集から学習し、今後の生成精度を向上させます。

当てはまらないもの

自己執筆型ドキュメントは、「コードベースのドキュメントを書いて」とプロンプトを入力して出力させたAI生成テキストではありません。そのようなアプローチでは、言語モデルが「あなたのシステムが何をしているか」を推測して書いたような、一般的で、しばしば不正確な文章が生成されてしまいます。

自己執筆型ドキュメントは、実際のPR、実際の会話、実際のミーティングといった、実際のエンジニアリング活動から生成されます。アウトプットは、モデルが起こったと「推測した」ことではなく、実際に「起こった」ことを記述します。引用元によって検証可能性が担保され、継続的な更新によって最新性が維持されます。そして、人間によるレビューが品質を保証します。

この違いは極めて重要です。なぜなら、ドキュメントに対する信頼は壊れやすいものだからです。自動生成されたドキュメントが不正確であると気づいたエンジニアは、古くなって放置された手書きのドキュメントを読まなくなるのと同様に、すぐにそれを読まなくなります。自己執筆型ドキュメントは、検証可能（すべての記述に情報源がある）で最新（システムの変化に合わせてドキュメントが更新される）であることによって、信頼を獲得します。

ソース

自己執筆型ドキュメントは複数のソースタイプから情報を取得でき、接続するソースが増えるほどカバー範囲が向上します：

GitHub：PRの説明、コミットメッセージ、コードレビューのコメント、Issueでの議論。これらは「何が、なぜ変更されたか」を捉えます。

Slack：設計の議論、アーキテクチャの検討、インシデント対応のスレッド、意思決定の会話。これらは、コードには残らない「背景にある思考」を捉えます。

ミーティング：スプリントプランニング、アーキテクチャレビュー、インシデントのふり返り、オンボーディングセッション。これらは、通常失われてしまう「口頭でのコンテキスト」を捉えます。

エンジニアリングチャンネル：技術的な議論が行われるエンジニア専用のSlackチャンネル、Discordサーバー、またはその他のコミュニケーションツール。

接続するソースが増えるほどドキュメントは包括的なものになり、ツール間の隙間で重要な知識がこぼれ落ちてしまう可能性が低くなります。

よくある質問

生成されたドキュメントの精度はどのくらいですか？ 精度はソースの品質によって異なります。明確な説明が記載されたPRの説明は、1行だけのコミットメッセージよりも優れたドキュメントを生成します。詳細なSlackの議論は、短いやり取りよりも優れたドキュメントを生成します。引用システムにより、エンジニアは元の情報源を確認して記述内容を検証できます。また、レビュープロセスによって、不正確な内容が信頼される前にキャッチされます。

セットアップにエンジニアの時間はどのくらいかかりますか？ ソースの接続は通常、1時間もかかりません。ソースが接続されると、システムはすぐにドキュメントの生成を開始します。継続的なレビュー時間は、手動でのドキュメント作成に通常費やされる週5時間と比較して、エンジニア1人あたり週におよそ10分から15分です。

システムがキャプチャする内容を制御することはできますか？ はい、可能です。システムが読み取るリポジトリ、Slackチャンネル、ミーティングのカテゴリを選択できます。プライベートチャンネル、機密性の高いリポジトリ、機密ミーティングは除外できます。

これはConfluence、Notion、あるいは既存のWikiに取って代わるものですか？ それらに取って代わることも、補完することも可能です。自己執筆型ドキュメントシステムは、手動のWikiと同じ目的を果たす構造化され検索可能なドキュメントを生成しますが、自動的に最新の状態に保たれるという利点があります。既存のWikiコンテンツは、生成されたドキュメントと並行して維持できます。

関連記事： エンジニアリングドキュメントが重要な理由、 ドキュメントのパラドックス、 エンジニアがドキュメント作成を嫌う理由、 自己執筆型ドキュメント vs Confluence。関連ページ： 自己執筆型ドキュメントについて、 エンジニアリングチーム向け。