documentation-information-architecture

ドキュメントの情報アーキテクチャ

このスキルを使用すると、読者が必要なときに適切なコンテンツを見つけられるよう、開発者向けドキュメントを整理できます。単一ページの文章ではなく、ドキュメントセットやサイト全体を対象とします。

このスキルは、Docs for Developers: An Engineer's Field Guide to Technical Writing、特に第10章「Organizing documentation」を基にしています。さらに、Christopher Gales と Splunk Documentation Team による The Product Is Docs: Writing Technical Documentation in a Product Development Group、特に第17章「Tools and Content Delivery」からの言い換えた指針と、第3章、第9章、第10章、第25章にある対象読者、学習目標、メンテナンス、SaaS に関する関連ガイダンスを加えています。書籍の文章をユーザー向けの出力に転載しないでください。出典：https://link.springer.com/book/10.1007/978-1-4842-7217-6

クイックスタート

1. guidelines.md を読み込み、役立つ最小限の参考資料セットを選びます。
2. ユーザーのメンタルモデル、よくあるタスク、既存コンテンツの一覧を確認します。
3. シーケンス、階層、ウェブの構造を選択するか、組み合わせます。
4. ドキュメント作成ツールを選定または移行する場合は、workflows/evaluate-doc-platform.md を使用します。
5. IA の全面的な監査または再設計には、workflows/audit-doc-ia.md を使用します。
6. リダイレクト、メタデータ、ソースに関する判断、メンテナンスルールを維持します。

既定の出力

IA を監査または再設計する際は、次の内容を返します。

1. 現状の調査結果 - ナビゲーション、不足、重複、古いコンテンツ、見つけやすさに関する問題。
2. ユーザーモデル - 主な対象読者、タスク、入口。
3. 推奨構造 - シーケンス、階層、ウェブ、ランディングページ、ナビゲーションの手がかり。
4. コンテンツの対応 - 維持、削除、確認、統合、分割、移動、作成。
5. 移行計画 - リダイレクト、メタデータ、担当者、検証。
6. メンテナンス計画 - IA に関する判断を最新の状態に保つ方法。

目次

必要なこと	ここから始める
IA パターンを理解する	references/core/knowledge.md
IA のルールを適用する	references/core/knowledge.md
IA の例を見る	references/core/knowledge.md
IA を監査または再設計する	workflows/audit-doc-ia.md
ドキュメントプラットフォーム／ツールを評価する	workflows/evaluate-doc-platform.md
タスクに応じて案内する	guidelines.md

基本方針

• ユーザーのメンタルモデルとタスクに沿ってドキュメントを整理します。
• ランディングページはすばやく案内するために使い、マーケティング目的の寄り道を作らないようにします。
• ナビゲーションの手がかりは役立つものにしつつ、必要最小限に抑えます。
• 移行とメンテナンスも IA 設計の一部として扱います。
• 機能への期待感ではなく、読者、執筆、メンテナンス、移行の要件に基づいてツールを選びます。