# General Translation Blog: 人間とエージェントのためにドキュメントを書き直す
URL: https://generaltranslation.com/ja/blog/rewriting-our-docs.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 13,000語のスタイルガイドで読み手の体験を設計し、エージェントが読み取りやすいようにドキュメントを構造化した取り組みについて。
Authors: Taylor Fang
Published: 2026-09-14

## 2 種類の読み手を見据えた設計

ドキュメントは、製品とその土台となる仕組みを伝えるものです。ユーザーが**製品とその仕組みについてのメンタルモデルを構築する**のを助け、直感的な流れに沿って導きながら、その過程で生じる疑問に答えるものでなければなりません。ドキュメントは、新しいユーザーには概念を噛み砕いて示し、習熟するにつれて複雑さを開示していく必要があります。

**さらに、新たな読み手も現れています。** エージェントは急速に人間のユーザーと並ぶ主役になりつつあり、ドキュメントを発見し、読み、解析するための専用の設計を必要としています。

[私たちのドキュメント](https://generaltranslation.com/en-US/docs/overview/get-started)は、プラットフォームが新しいフレームワークやインテグレーションに対応していくのに合わせて、自然発生的に拡大してきました。しかし、構成、順序、言葉遣いに次第にばらつきが生じ始めました。

そこで私たちは、人間とエージェントの双方にとっての読み手体験を意識しながら、ドキュメントをゼロから作り直すことにしました。**最初のリファクタリングで手を入れたのは 900 ファイル** (+31,868 / −32,249 行) です。対象読者、ページ構成、文体と文法に関するルールを定めた 13,000 語のスタイルガイドも作成しました。現在、ドキュメントはスタイルガイドに対して lint を実行する日次のクラウドエージェントによって保守されています。

エージェントが読み取りやすいよう、機械可読な発見と取得のための [`llms.txt`](https://generaltranslation.com/llms.txt) と [`llms-full.txt`](https://generaltranslation.com/llms-full.txt) も提供しており、URL に `.md` または `.mdx` を付けることでどのドキュメントページも生Markdown として取得できます。また、[コーディング エージェント向け](https://generaltranslation.com/en-US/docs/overview/for-coding-agents)のドキュメントページを用意し、エージェントにセットアップ方法、使い方、正しい翻訳方法を伝える drop-in の `AGENTS.md` を、ホスト型の MCP サーバーおよび機械可読な OpenAPI 仕様とあわせて提供しています。

この Post では、私たちが行った変更と、そこから得た学びを紹介します。

## インスピレーション

私たちは、ベストプラクティスや「これはいい」と思う開発者向けドキュメントを調査し、そこからインスピレーションを得ました。

* Lee Robinson の[ドキュメント](https://leerob.com/docs)論。**「初めての体験はシンプルに保ち、複雑さは少しずつ明かしていく」**。彼が挙げる10の原則は、高速であること、読みやすいこと、AIネイティブであること、洗練されていること、レスポンシブであること。そしてもちろん、ローカライズされていることです。 (実際、私たちは Lee と一緒に [Cursor のドキュメントをローカライズ](https://www.linkedin.com/posts/leeerob_just-shipped-new-docs-for-cursor-been-hacking-activity-7374285675900297216-veY1/)しました！) 
* Fuma Nama の[ドキュメント](https://www.fuma-nama.dev/blog/good-docs)論。彼はシンプルな文体を勧め、太字、見出し、ハイパーリンク、リスト、表を使って**より論理的な構造を組み立てる**ことを推奨しています。さらに Fuma は、読者体験においてナビゲーションはコンテンツ以上に重要になり得るとも述べています。 (Fuma の考え方については、インタビュー記事で[詳しく読む](https://generaltranslation.com/en-US/blog/fuma-nama)ことができます。) 
* Devin Logan の[エージェント対応ドキュメント](https://buildwithfern.com/post/agent-friendly-docs)論。Devin は、**ユーザーがエージェント経由でドキュメントにアクセスすることが新たな前提になっている**と指摘します。そのうえで、AI にとっての読みやすさを実現する手順を示しています。コンテンツ面では、システムを説明し、実行可能な手順を提示すること。プラットフォーム面では、ページがエージェントから見つけやすく、余計な要素をそぎ落とした形になっていることです。
* 私たちが気に入っている開発者向けドキュメントも細かく見ていきました。明快さとシンプルさの [Linear](https://linear.app/docs)、分かりやすい階層ナビゲーションの [Replicate](https://replicate.com/docs)、美しいデザインの [shadcn/ui](https://ui.shadcn.com/docs)、開発者に寄り添った言葉遣いとコミュニティ機能の [Next.js](https://nextjs.org/docs)、心地よいビジュアルの [Convex](https://docs.convex.dev/home)、埋め込み機能の [Stripe](https://docs.stripe.com) など、数多くのドキュメントです。

## ユーザージャーニー

技術的な機能を淡々と説明するのではなく、**ユーザーが何を達成したいのか**を軸にページと文言を再構成しました。すべてのセクションは、Quickstart、Guides、Reference という一貫した骨格に沿っています。

![ユーザーの3つの疑問が、それぞれ Quickstart、Guides、Reference というドキュメントページの種類に振り分けられる図](/static/blogs/rewriting-docs-spine.png?v=20260914-1722)

Guides のタイトルは動名詞、つまり**ユーザーが片付けたい仕事**として表現しています。たとえば「Reviewing and editing translations」や「Handling plurals and branches」といった具合です。ある workflow を完了させたい新規ユーザーは、どの reference 用語で検索すればよいか悩む必要がなく、自分が取りたい操作をそのまま検索できます。

うれしい副次効果として、**ドキュメントの Guides 自体が SEO で上位に表示される**ようになりました。「React managing locales」「React translating jsx」「Configuring a Vite SPA i18n」「React plurals and branches」「Translating rrweb」など、多くの検索で Google の最上位に表示されています。

ドキュメントサイト自体は [Fumadocs](https://www.fumadocs.dev) 上に構築されています。先日、その作者に、美しくコンポーザブルな reader experience についての考え方を[インタビュー](https://generaltranslation.com/en-US/blog/fuma-nama)しました。

## 論理的で直感的な導線

ドキュメントは、ユーザーが製品とその仕組みについてのメンタルモデルを築く手助けとなるべきものです。そのためには、ナビゲーションと各ページの両方で直感的な導線が欠かせません。並び順は意図的かつ意味のあるものにし、**論理的にグループ化したうえで、読者が実際に作業を行う順番に沿って配置する**必要があります。目指すのは学習曲線に寄り添うことです。初心者が正しい文脈を無理なく築けるようにしつつ、読み進めて理解が深まるにつれて複雑な内容やカスタマイズが姿を現すようにします。優れた導線とは、その存在を意識させないものです。

**a) 構造。** ドキュメントの構造と順序はCIで担保されており、トップレベルのセクションを固定するチェックによって、新しいページが既存の情報アーキテクチャに自然と収まるようになっています。

![リデザイン前後のドキュメントサイドバー。Overview、Platform、フレームワーク、インテグレーションのセクションを軸に再編成されている](/static/blogs/rewriting-docs-sidebar.png?v=20260914-1722)

**b) 関連ページ。** 各ページはユーザーを次のステップへと導き、関連リンクは論理的な近さに基づいて更新されます。入口となるページは最大4つの関連するGuidesへ、各Guideは関連するGuidesへとつながります。リンクは本文ではなくfrontmatterに置いているため、サイト側でリンク先をページツリーと照合して解決できます。

![Next stepsコンポーネント。ページを最も関連性の高い4つのガイドへリンクしている](/static/blogs/rewriting-docs-frameworks.png?v=20260914-1722)

**c) ユーザーの選択。** ドキュメントサイトはユーザーの選択を記憶し、最後に選ばれた言語とテーマでコンテンツを自動的に表示します。code blocksでも、ユーザーが選択したフレームワーク (React／Next.js／TanStack Start／React Native) やパッケージマネージャー (npm／yarn／bun／pnpm) のタブが自動的に維持されます。

![React、Next.js、TanStack Start、React Native のフレームワークタブを備えた共有コードブロック](/static/blogs/rewriting-docs-next-steps.png?v=20260914-1722)

**d) リンクのパス。** リンクのパスもまた細やかな工夫のひとつです。スラッグは単なるページタイトルではなく、曖昧さが生じない範囲で最も語数の少ないものにしています。文言や内容が変わっても、リンクと見出しのアンカーはそのまま維持されます。さらに、綴りの誤ったURLを捕捉して**最も近い候補へリダイレクト**するか、最も近い5つのページを示す専用の404を返す仕組みも組み込んでいます。

![ページが見つかりませんという表示。ドキュメント内で最も近い5つのページへのリンクが並んでいる](/static/blogs/rewriting-docs-not-found.png?v=20260914-1722)

## シンプルな言葉づかい

プラットフォームには多様なユーザー像が存在するため、言葉づかい自体もシンプルさと明確さを重視しています。各ページでは、**仕組みの説明に入る前に、まずそのページが何を扱い、どんなときに使うのかを読者に示します**。各セクションも**焦点が絞られ、単独で完結したまとまり**になっており、結果として人間にとってもエージェントにとっても読みやすくなっています。

各ページは特定の読者層に向けて、その層に合わせて書かれています。ドキュメントのスタイルガイドより:

<Callout type="info" icon=" " className="w-full max-w-none rounded-md border-0 bg-fd-muted p-5 shadow-none [&>div:first-child]:hidden [&_p]:my-3! [&_ul]:my-3! [&_li]:my-3! [&_p]:leading-snug! [&_li]:leading-snug!">
  **読者層**

  そのページの読者に向けて書き、内容の深さと語彙を読者に合わせること:

  * 技術的な開発者向けページ。読者は SDK、CLI、API を組み込む開発者です。型、パラメータ、ヘッダー、デフォルト値、エラー時の挙動を正確に記述し、実行可能な例を示すこと。LLMs やエージェントが読み取れる、機械可読なドキュメントにもすること。
  * 非技術的なプロダクト向けページ: Dashboard と Locadex。読者は Dashboard の UI で作業するローカライゼーション担当者、翻訳者、PM です。成果と UI 上の操作を先に示し、概念は平易な言葉で説明すること。

  すべての読者層に共通する明確さのルール:

  <Check className="inline size-4 align-[-3px] text-green-600 dark:text-green-500" strokeWidth="3" /> 「どう使うか」より先に「何であるか」「なぜ必要か」を示す。

  <Check className="inline size-4 align-[-3px] text-green-600 dark:text-green-500" strokeWidth="3" /> 1 文につき 1 つの考えにとどめ、短い文を優先する。

  <Check className="inline size-4 align-[-3px] text-green-600 dark:text-green-500" strokeWidth="3" /> 用語は初出時に定義し、略語は初出時に正式名称を示す。

  <X className="inline size-4 align-[-3px] text-red-600 dark:text-red-500" strokeWidth="3" /> まだ説明していない概念、製品用語、設定をいきなり使わない。

  <X className="inline size-4 align-[-3px] text-red-600 dark:text-red-500" strokeWidth="3" /> 説明のない専門用語は避ける。避けられない用語で、1 文で説明するには複雑すぎる場合は、定義されている箇所へリンクする。
</Callout>

また、特定のユーザー像に向けたページも用意しました。ローカライゼーションが初めてのユーザー向けには、[キーコンセプト](https://generaltranslation.com/en-US/docs/overview/key-concepts)のページで、internationalization、ローカライゼーション、翻訳、ロケール、context といった中心的な概念を平易な言葉で説明しています。主にエージェントを使うユーザー向けには、[コーディングエージェントの利用](https://generaltranslation.com/en-US/docs/overview/for-coding-agents)のページが、機械可読なドキュメント、MCP サーバー、そのまま使える `AGENTS.md` ガイド(詳細は後述)へとエージェントを導きます。

## エージェントに読ませるための設計

[複数](https://www.mintlify.com/blog/state-of-ai)の[情報源](https://blog.cloudflare.com/markdown-for-agents/)が指摘しているとおり、いまやドキュメントの読者の大半はエージェントです。そのため、LLMフレンドリーであることは最優先事項です。読みやすさや構成に関する原則の多くは人間向けの内容にもエージェント向けの内容にも同じように当てはまりますが、エージェントには専用の**発見・取得・ツールアクセスの機能**が必要です。

私たちは、Vercelの[Agent Readability spec](https://vercel.com/kb/guide/agent-readability-spec)と[AFdocs spec](https://afdocs.dev)に基づいてエージェント対応を設計しました。この2つの仕様は、AIエージェントがどのようにコンテンツを見つけて解析するかという観点から、重要な問いに答えるものです。エージェントはドキュメントのページを発見し、その内容を辿れるか。コンテキストウィンドウに収まるクリーンなMarkdownコンテンツを読めるか。検索・取得を行い、適切なAIツールを使えるか。

実装の主なポイントは次のとおりです。

* [`llms.txt`](https://generaltranslation.com/llms.txt): [llmstxt.org](https://llmstxt.org)標準に準拠したドキュメントの索引。加えて[`llms-index.txt`](https://generaltranslation.com/llms-index.txt) (全ページ) 、[セクションごとの索引](https://generaltranslation.com/docs/react/llms.txt)、[`llms-full.txt`](https://generaltranslation.com/llms-full.txt) (より大きなコンテキストを読み込めるツール向けの全コーパス) というレイヤーも用意
* [`sitemap.xml`](https://generaltranslation.com/sitemap.xml)と[`sitemap.md`](https://generaltranslation.com/sitemap.md): 全ページの機械可読なマップ
* 全ページの生Markdown: 任意のドキュメントURLに`.md`または`.mdx`を付けるだけです。`Accept: text/markdown`を送信する既知のAIクローラーやエージェントには、自動的にMarkdownが返されます
* streamable HTTPを使う認証付きのMCP (Model Context Protocol) サーバー: [`https://api.gtx.dev/mcp`](https://api.gtx.dev/mcp)
* [`/openapi.json`](https://generaltranslation.com/openapi.json) (および[`/openapi.yaml`](https://generaltranslation.com/openapi.yaml)) で提供する機械可読なOpenAPI仕様。各エンドポイントのリファレンスページからリンクしています
* RAG (検索拡張生成) 向けにチャンク単位で構造化されたコンテンツ。各セクションは一つの完結した内容を扱い、見出し階層も一貫しています
* AIクローラーがすべての公開ページにアクセスできる、寛容な[`robots.txt`](https://generaltranslation.com/robots.txt)

## プロセス、メンテナンス、スタイルガイド

![最初のドキュメントリファクタリング: 900ファイルを変更し、31,868行の追加と32,249行の削除](/static/blogs/rewriting-docs-diff.png?v=20260914-1722)

このドキュメントの大規模なリファクタリングは、1人の人間のライター (私です！) とさまざまなAIツールの協働で進め、チームの他のメンバーからも意見をもらいました。私たちの原則は、**コンテンツ・意味・論理の流れの理解は人間の執筆力と判断力で担保し、そこで得た知見を厳密で網羅的なスタイルガイドに落とし込み、AIによってスタイルガイドをスケールさせ、コードベース**の更新に追随し続ける、というものです。

まず網羅的な調査パスを実行し、**900ページ、117,000語以上の文章にわたる既存ドキュメントの全コンテンツのインベントリ**を作成しました。この素材のインデックスをもとに、手書きのマップに沿ってコンテンツを再構成しました。必要な最上位セクションは何か、フレームワークをどうグループ化しどう並べるか、各ページの目的は何か、といった観点です。各セクションの代表的なページは自分で執筆・編集し、明快さ、シンプルさ、ユーザージャーニーの支援という原則を反映させました。この手作業の部分だけで、1か月以上の集中的な作業を要しました。特にQuickstartは多くのテストを必要とし、私たちのi18n libraryのエンジニアが大幅に手を入れています。

![Cursorでドキュメントを編集する様子。ソースのMDXがレンダリングされたMarkdownプレビューの隣に表示されている](/static/blogs/rewriting-docs-cursor.png?v=20260914-1722)

このプロセスで特に面白かったのは、Markdownプレビューパネルを活用しながらCursorで直接執筆した点です。おかげで私の変更内容がバージョン履歴として正確に残り、その後エージェントに**私の変更 (さらには思考プロセス) をガイドラインやルールへと一般化し、ドキュメントのスタイルガイドに追加して、全ページに適用する**よう手軽に頼めるようになりました。構造であれコンテンツであれ、ドキュメントに編集を加えるたびに、その変更を一般化してスタイルガイドとともに適用しています。

その結果、私たちの[ドキュメントスタイルガイド](https://github.com/generaltranslation/content/blob/main/DOCS-SKILL.md)は非常に詳細で、**私たちのドキュメントの方針にぴったり沿ったもの**になっており、さまざまなエッジケースやユーザーの目的を網羅し、830行・13,000語を超えています。このスタイルガイドはCIで強制され、エージェントが容易に適用できる一連の運用手順であり、メタ的な執筆原則から非常に具体的なルールやスキルまでをカバーしています。**さらに、クラウドエージェントが毎日実行され、ドキュメントを実際にリリースされた挙動と同期させます。** エージェントはカバレッジの抜け、不正確な記述、古くなった例を探します。新規プロジェクトを立ち上げて機能をローカルでテストし、スタイルガイドに従って文章をlintもします。

これらのスタイルガイドのルールは、お客様向けの翻訳品質のために適用している[contextとカスタムプロンプトのルール](https://generaltranslation.com/en-US/docs/platform/dashboard/guides/defining-context-for-translations)と似ています。

## パート2: ビジュアルデザイン

こうした構成の見直しによって、ドキュメントがより直感的で使いやすくなっていれば幸いです。ご意見・ご感想はいつでも歓迎します。各ドキュメントページには、ページの編集、問題の報告、質問のためのボタンが用意されています。

ブログのパート2では、ドキュメントのUIとインタラクションの再設計、そして[Fumadocs](https://generaltranslation.com/en-US/blog/fuma-nama)上で独自のビジュアルをどのように構築したかを紹介します。ぜひご期待ください。

![各ドキュメントページにあるフィードバックバー: ページを編集する、GitHubで問題を報告する、質問する](/static/blogs/rewriting-docs-footer.png?v=20260914-1722)

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.