ハクソク

世界を動かす技術を、日本語で。

AIのためのドキュメント作成：ベストプラクティス

341日前原文(docs.kapa.ai)

概要

  • RAGシステム （例：Kapa）は、 高品質なドキュメント に依存
  • 人間とAI の両方に適したドキュメントが、 相互強化ループ を生む
  • AIが処理しやすい構造 や明確さが、 回答精度向上 に直結
  • チャンク化 や 明示的記述 がAI活用の鍵
  • 実践的な最適化手法 と よくある課題 の解決策を紹介

RAGシステムとAIに最適なドキュメント作成ガイド

  • Retrieval-Augmented Generation (RAG)システム は、 正確なドキュメント を元にユーザー質問へ回答
  • 質の低いドキュメント は、人間にもAIにも悪影響
  • AIシステム は、 明示的で自己完結した情報 を必要とする
  • チャンク単位 で情報を処理、 文脈や暗黙知の推論は困難
  • 高品質なドキュメント は、 AIの回答精度とユーザー体験 を大きく改善

AIがドキュメントを処理する仕組み

  • Retriever ：ユーザー質問に合致する情報を検索
  • Vector database ：情報を検索しやすい形で保存
  • Generator（LLM） ：検索結果を元に回答を生成
  • 処理フロー ：インジェスト → クエリ変換 → 検索 → 回答生成
  • チャンク化 により、 情報の独立性・明確性 が重要

AI向けドキュメント最適化のポイント

  • チャンク化 ：意味のまとまりごとに分割し、 関連情報の近接配置 を意識
  • 明示的記述 ： 暗黙の前提や省略 は避け、 必要情報を明確に記述
  • 一貫性のある用語 ：製品名や機能名を 明確かつ統一的 に使用
  • 構造化 ： 見出し、リスト、表 などを適切に活用し、 階層構造 を明示
  • 自己完結性 ：各チャンクが 単独で意味を成す よう配慮

ドキュメント最適化の実践ポイント

  • HTMLのセマンティック要素 （例：<h1>、<h2>、<ul>、<ol>、<table>）を正しく使用
  • PDFよりHTMLやMarkdown を推奨、 機械可読性と抽出精度 が向上
  • クローラー対応 ：シンプルなHTML構造、 複雑なJSやUI要素は避ける
  • 意味明瞭な見出し・URL ：内容を反映し、 階層構造を意識
  • 図やチャートのテキスト説明 を必ず付与
  • レイアウト依存の意味付けは避ける ： 見出し・リスト・段落 で構造化

AIドキュメント設計における課題と解決策

文脈依存の分断（Contextual Dependencies）

  • 情報が分散 すると、 チャンク分割時に文脈が失われる
  • 関連情報は近接配置 し、 同一段落や隣接段落 で記述
  • 例 ：制約条件と実装指針を分けず、 一体で記載

セマンティック検索の抜け漏れ（Semantic Discoverability Gaps）

  • 重要用語や製品名が未記載 だと、 検索・抽出精度が低下
  • 製品・機能名を明示的かつ一貫して記載
  • 構造メタデータ （見出し・URL）も活用し、 文脈を補強

暗黙知への依存（Implicit Knowledge Assumptions）

  • AIは明示情報のみ利用可能、 推論や常識的判断は不可
  • 必要な前提や背景知識は必ず明記
  • ユーザーが知っている前提での省略は避ける

まとめと推奨事項

  • AI・人間双方にやさしいドキュメント は、 明快な構造・明示的記述・自己完結性 が鍵
  • 定期的なドキュメント見直し と AI回答のフィードバック活用 で、 継続的な品質向上
  • RAG時代のドキュメント整備 は、 プロダクト価値向上とAI活用の基盤

さらに深い課題や設計パターンの詳細は、 Content design challenges for AI などの専門セクションで補完

Hackerたちの意見

OPです。ドキュメントをAIフレンドリーにすることが、実は良いドキュメントの本質そのもの（明確なコンテキストと階層、自己完結したセクション、正確なエラーメッセージ）になっちゃうのが皮肉だよね。

└

みんな、今はより良いインセンティブがあるからね :)

└

コードを書くのも似たような感じだよね。突然、みんなが自分の問題をLLMに説明して、解決するために小さなサブ問題に分けてるし…。

└

関連情報: 「AIエージェントがあなたのAPIの使い方を理解できないなら、ユーザーも理解できない」 （私の会社のブログから） https://stytch.com/blog/if-an-ai-agent-cant-figure-out-how-y...

└

これを共有してくれてありがとう。トップダウンの学習リソースとしてすごく役立つよ。今、AIを使う方法を学んでいるところで、技術的なコンテンツのためにローカルのセマンティックサーチを使ったものを自作してるんだ（Ollama経由での埋め込みモデル、ChromaDBでのインデックス作成）。今は、非構造化の知識をクエリ可能にする段階で詰まってるから、これらのドキュメントは絶対に役立つと思う。改めてありがとう！

└

SEOも同じだね。良い構造、正しいHTML要素の使い方、速い読み込み、良いアクセシビリティなど。確かにSEOを改善するための「トリック」もあるけど、一般的な原則はSEOをやっていない場合でも良いよ。

└

これが「プロンプトエンジニアリング」の面白いところだよね。要するに、効果的な言語学やスピーチなんだ。昔から「ソフトスキル」って呼ばれてたものが、今や何かの科学になろうとしてるのが明らかだね。

└

ドキュメントを書く立場から見ると、現在のLLMは、研究に参加したいユーザーを見つける苦労をほとんど解決していることに気づいたよ。彼らは主にリテラシーがあって、基本的に無能なんだ。

└

アシモフの話を思い出すな。主人公がある公人がロボットだと信じていて、ずっと証明しようとしてたんだ。結局、実際にロボットか「ただのすごい人間か」を見分けるのは不可能だって結論に達したんだよね。

└

提案を2つのカテゴリーに分けられるよ。1つ目は、W3Cが20年前にウェブを良くするために研究して定義したこと。アクセシビリティや、JSなしで動くセマンティックなシンプルHTML、標準フォーマットとかね。ほとんどの企業はこれを無視したり、脇に置いたりしてる。2つ目は、現在のLLM技術の明らかな限界（コンテキストのサイズや曖昧さなど）を回避するための提案。カテゴリー1については、もう多くの人が言っていて、ほとんどバカにされてたから、話すことはあまりないよ。カテゴリー2については、AIの失敗を受け入れる最初の段階だね。「ああ、これじゃ人間のコンテンツを信頼して推論できない。でも、もっとバカなことを書かせたらどうなる？」って感じ。

└

それに、人間にもアクセスしやすくなるんだ。今、AppleのJSが多いドキュメントサイトをAI向けにマークダウンに変換するプロジェクトもあるよ。

あのサイトでダークモードをオフにするにはどうすればいいの？目が痛いんだけど。

└

フィードバックありがとう。絶対にそれを追加すべきだね :)

└

Firefoxでは、リーダービュー（F9）がうまく処理してくれるみたい。

新しいAI向けのSEOの罠にハマらないようにね。LLMはユーザーと同じだから。 https://passo.uno/writing-for-llms-ai-chatbots/

└

この文書に書かれていることのほとんどは、人間にも良いことだよ。理由は違うけど、結果は同じ。

AIがあれば、ユーザー向けのドキュメントを簡単に作れるよ！ > ステップ1、自分でドキュメントを書く。 > ステップ2、ボットがあなたのウェブサイトに毎分何百回もアクセスする。 > ステップ3、ユーザーはあなたのサイトに来ない、OpenAIのサイトを使う。 > ステップ4、？？？ OpenAIが利益を得る。

└

もしあなたのソフトウェアビジネスが、人がサイトに来てドキュメントを読むことに依存しているなら、最初から詰んでるよ。それは、ユーザーがあなたのサイトにいるか、ChatGPTにいるか、どこにいてもサポートすることが大事なんだ。

良いドキュメントは悪いアプリやAPIを直すわけじゃないけどね。ドキュメントの需要があるってことは、DXにもっと深い問題があるサインだと思う。良いドキュメントは、最初に他のDXに十分な愛情を注いだ場所にしか存在しないから、質の印であって、質を得る手段ではないんだ。

└

そうだね、ドキュメントを作ることは全体の体験を理解するための練習だよ。実際、チームの誰もが本当にそれを理解しているわけじゃないことが多い。

ちょっと話がそれるけど、最近「plan.txt」ファイルをclaudeのコード用に書くことが多くなってる。1. プランを書く 2. Claudeに理解度をレビューしてもらう 3. 明確になるまで必要に応じて更新 4. プランのタスクを実行。最初の段階でClaudeがかなり進むことが分かってる。プランのバージョン管理もできるしね。

└

なんでプログラミングを学ぶことに興味がないの？

サイトの隅にあるウィジェットが動いて注意を引こうとすると、すぐに離脱しちゃう。もし彼らが本当に人に記事を読んでもらいたいなら、読者が読み始めた瞬間に気を散らすようなことはしない方がいいよ。

└

サイトの隅にあるウィジェットが動いて注意を引こうとすると、すぐに離脱しちゃう。昔HNで見つけたブックマークレットがあるんだ。ホットキーに割り当ててるから、ウェブサイトがそんなバカなことをしたら、キーストロークで消せるよ。大体90%の確率でうまくいくし、何もインストールする必要もない。javascript:(function()%7B(function%20()%20%7Bvar%20i%2C%20elements%20%3D%20document.querySelectorAll('body%20*')%3Bfor%20(i%20%3D%200%3B%20i%20%3C%20elements.length%3B%20i%2B%2B)%20%7Bif%20(getComputedStyle(elements%5Bi%5D).position%20%3D%3D%3D%20'fixed')%20%7Belements%5Bi%5D.parentNode.removeChild(elements%5Bi%5D)%3B%7D%7D%7D)()%7D)()

問題のアプリがオープンソースだと仮定した場合、すべてがそうではないけど、AIがソースコードを読めるなら、なぜドキュメントを読む必要があるの？

└

ドキュメントはコード（機能）の要約とユースケースの両方の役割を果たしている。AIがコードから両方を完璧に推測できる日が来たら、その時こそAIが依存関係を即座に書けるようになるんだ。

└

ドキュメントは、意図やデザインの決定、使い方のパターンを伝えてくれるんだ。これらはソースコードの中に散らばっていることが多いから、コードがあっても価値があるよ。

└

コードは最終的な実装だから、君やAIはコードを読んで何をするか説明できるけど、なぜそれが書かれたのか、いつ使うべきかはもっとコンテキストがないと説明できないんだよね。

このガイドは、RAGシステムにおいて人間の読者とAI/LLMの両方に効果的なドキュメントを作成するためのベストプラクティスを提供します。私が興味があるのは、RAGシステム専用に消費されることを前提としたドキュメントを作成するためのベストプラクティスで、これがずっと簡単で安価にできるという仮定に基づいています（そして、異なるシナリオに最適な出力を生成するためのプロンプトシステムに対する対応するベストプラクティス）。

APIと対話するエージェントを構築することで見つけた効果は、そのボットがエラーハンドリングのスモークテストとして機能することだよ。もしあなたのAPIが明確で実行可能なエラーを返さない、またはJSONフィールドを明確に正しく検証しないなら、そのボットはそれを見つけて混乱することになる。近い将来、CRUDエンドポイントがAIサービスによって完全にテストされ、ドキュメントを読み、エンドポイントをナビゲートし、不整合や欠陥を見つける様子が想像できるよ。