documentation-platform-selection

ドキュメントプラットフォームの選定

このスキルは、ドキュメントプラットフォームや執筆ツールの選定、比較、試験導入、移行に役立ちます。読者の体験、執筆者のワークフロー、現実的な保守性、移行リスクを軸に判断できます。

このスキルは、Christopher Gales と Splunk Documentation Team による The Product Is Docs: Writing Technical Documentation in a Product Development Group の第17章「Tools and Content Delivery」を中心に、保守性や読者に関する第3章および第10章の関連ガイダンスを言い換えてまとめたものです。書籍の文章をそのままユーザー向けの出力にコピーしないでください。出典：https://link.springer.com/book/10.1007/978-1-4842-7217-6

クイックスタート

1. guidelines.md を読み、必要最小限の参考資料を選びます。
2. 現在の課題、目指す読者体験、執筆者のワークフロー、制約を明示します。
3. 選択肢を比較するには、workflows/evaluate-doc-platform.md を使います。
4. 移行または試験導入の計画が必要な場合は、workflows/plan-doc-migration-pilot.md を使います。
5. ツールの問題と、プロセス、責任分担、情報アーキテクチャの問題を切り分けます。
6. 要件、比較、推奨案、移行リスク、試験導入計画、未解決の質問を提示します。

デフォルトの出力

ドキュメントプラットフォームを評価する場合は、次の内容を提示します。

1. 判断の背景 - 現在の課題、対象読者、コンテンツの種類、チームのワークフロー、制約。
2. 要件 - 読者、執筆、コンテンツモデル、連携、保守、移行、可搬性、サポート、コスト。
3. 選択肢の比較 - 重み付けしたトレードオフ、適合性、リスク、導入に必要な負担。
4. プロセス上の課題 - ツールだけでは解決できない、責任分担、IA、レビュー、メタデータ、保守に関する問題。
5. 推奨案 - 継続、プロセスの改善、試験導入、移行、または却下。
6. 試験導入または移行計画 - 範囲、成功基準、ロールバック、担当者、スケジュール。

目次

必要な内容	ここから開始
プラットフォーム選定の概念を理解する	references/core/knowledge.md
ツールを評価して比較する	workflows/evaluate-doc-platform.md
移行または試験導入を計画する	workflows/plan-doc-migration-pilot.md
タスクや症状に応じて案内する	guidelines.md

基本方針

• ベンダーの機能ではなく、読者と執筆者にとっての成果から始めます。
• ツールのせいにする前に、プロセスの問題を診断します。
• 移行は、コンテンツ、URL、メタデータ、検索、ワークフローの変更として扱います。
• ベンダーロックインを意図的なトレードオフとする場合を除き、可搬性を優先します。
• チームが実際に保守できるプラットフォームを選びます。