user-guide-writing

ユーザーガイドの執筆

成果物が製品でのワークフローを完了するために役立つ、顧客向けまたは管理者向けのドキュメントである場合は、このスキルを使用します。

user-guide-writing は、ドキュメント作成スキル群の中核となるスキルです。対象は以下のとおりです。

• はじめての利用者向けガイド／最初の成功体験に導くガイド
• チュートリアルと手順に沿った解説
• タスクベースのハウツー記事
• FAQ とサポート向けの回答集
• UI やワークフローの変更がリリースされた後の、リリースに合わせたヘルプの更新
• 1 つの主要ページと、必要最小限の補足ドキュメントを組み合わせた小規模なガイド一式

モードや範囲を決める前に、以下の補足ドキュメントを読んでください。

• references/document-modes-and-boundaries.md
• references/mode-structures.md
• references/workflow-checklist.md
• references/maintenance-signals.md

このスキルを使う場合

• 新規ユーザーが最初の成果を上げられるようにする、はじめての利用者向けガイドが必要な場合。
• 機能のリリースに合わせて、実際の製品ユーザー向けのチュートリアルやハウツー記事が必要な場合。
• ヘルプセンターに、タスクベースの記事、FAQ、またはトラブルシューティングに役立つ手順ガイドが必要な場合。
• サポート上の問題が繰り返し発生しており、その回答を永続的な顧客向けドキュメントにする必要がある場合。
• ワークフローが変更され、既存のユーザー向け手順、スクリーンショット、警告、または前提条件を更新する必要がある場合。
• 用途が混在した巨大なドキュメントではなく、1 つのガイドと小規模な補足資料一式が必要な場合。

このスキルを使わない場合

• 主な目的が社内仕様書、アーキテクチャ文書、ADR、運用手順書、移行計画、または開発者向け実装ガイドの場合 → technical-writing を使用します。
• 主な目的が API リファレンス、SDK ドキュメント、Webhook ドキュメント、開発者向けクイックスタート、または開発者ポータルのコンテンツの場合 → api-documentation を使用します。
• 主な目的がリリースノート、CHANGELOG.md、移行のお知らせ、またはリリース済み変更の要約の場合 → changelog-maintenance を使用します。
• 主な目的がスライド資料、リリースプレゼンテーション、ワークショップ用スライド一式、またはビジュアルレビュー用の成果物の場合 → presentation-builder を使用します。
• 主な目的が製品のポジショニング、マーケティングメッセージ、ライフサイクルメールのコピー、またはリリース時のコピーの場合 → marketing-automation を使用します。
• 主な目的がアプリ内オンボーディングの仕組みや製品ツアーの UX の構築の場合 → まず該当する製品／UX スキルを使用し、その後、このスキルを使って継続的に参照できる補足ドキュメントを作成します。

手順

ステップ 1：主要モードを 1 つ選ぶ

執筆を始める前に、依頼の内容を整理します。

user_guide_mode:
  primary_mode: getting-started | tutorial | how-to | faq | release-help-update
  audience: end-user | admin | manager | mixed | unknown
  experience_level: first-time | familiar | advanced | mixed | unknown
  docs_surface: help-center | docs-site | in-app-companion | pdf | unknown
  source_of_truth: product-ui | release-notes | support-tickets | sme-notes | mixed | unknown
  maintenance_need: one-off | recurring | stale-doc-rewrite | launch-critical
  output_shape: single-page | guide-plus-faq | refresh-packet | guide-set | unknown

1 回の実行につき、主要モードを 1 つ使用します。

• getting-started → 最初の成果に至る最短経路
• tutorial → コンテキストとマイルストーンを含む、学習を導くガイド
• how-to → 1 つの実用的なタスクをすばやく完了する手順
• faq → 簡潔なよくある質問と、詳細なガイドへの案内
• release-help-update → リリース済みの UI またはワークフローの変更に伴う、ユーザー向けドキュメントの更新

ステップ 2：対象読者、タスク、案内先を確認する

執筆前に、以下を確認します。

1. 誰がこのドキュメントに従うのか。また、その人の役割や権限は何か。
2. 達成すべき具体的なタスクや成果は何か。
3. ワークフローを妨げる可能性のある前提条件、プランの制限、環境に関する想定は何か。
4. 範囲外とすべき関連スキルはどれか。

簡易案内先テーブル：

依頼が次のような内容の場合...	使用するもの
「アーキテクチャ文書／運用手順書／移行計画を作成する」	technical-writing
「開発者ポータル／SDK クイックスタート／Webhook ドキュメントを作成する」	api-documentation
「今回のリリースで提供された内容を要約する」	changelog-maintenance
「オンボーディングドキュメント／チュートリアル／FAQ／ヘルプ記事を作成する」	user-guide-writing
「リリース用スライド／研修用スライド／操作ガイドのプレゼンテーションを作成する」	presentation-builder

ステップ 3：ユーザー向けの最小限の根拠を集める

根拠のない感覚だけで草案を作成しないでください。まず、信頼できる最小限の根拠を集めます。

• 現在の UI ラベル、ナビゲーション、状態
• 前提条件、権限、プラン／エディションに関する想定
• 各重要ステップの後に期待される結果
• 発生しそうなブロッカー、空の状態、分岐条件
• 混乱を減らせる場合に限ったスクリーンショットまたはスクリーンショットのプレースホルダー
• 利用可能であれば、サポートへの問い合わせ、検索語、繰り返し発生している失敗の兆候
• 現行ガイドを古くしたリリースの変更点

詳細が不完全な場合は、ガイドが検証済みであるかのように装わず、想定を明示してください。

ステップ 4：最適な最小構成を選ぶ

references/mode-structures.md を使用し、選択したモードに必要なセクションだけを残してください。

ルール：

• リクエストがユーザーの成果を 1 つだけ扱う場合は、単一ページを優先します。
• タスクにメインガイドと、繰り返し発生するブロッカーへの対応が必要な場合は、ガイドと FAQを使用します。
• 主な作業がリリース後に古くなったページを修正することである場合は、マニュアル全体を書き直すのではなく、更新パケットを使用します。
• 1 つの草案でオンボーディング、日常的な使い方、トラブルシューティング、リリースノートをすべて扱うことになる場合は、小規模なガイドセットに分割します。

ステップ 5：役立つ最小限の成果物パケットを作成する

出力形式のデフォルト：

• single-page → 1 つのスタートガイド、チュートリアル、ハウツー、または FAQ ページ
• guide-plus-faq → 1 つのメインガイドに、短い FAQ またはトラブルシューティングの付録を追加
• refresh-packet → 変更された手順、古くなったスクリーンショットの一覧、影響を受ける関連ドキュメント、確認が必要な想定
• guide-set → スタートガイド＋FAQ、またはチュートリアル＋ハウツーのフォローアップなど、範囲を限定したセット

リクエストで必要なのが 1 ページと短い同期リストだけなら、包括的なハンドブックを作成しないでください。

ステップ 6：ユーザー向けドキュメントの執筆ルールを適用する

• 実装の詳細ではなく、タスクと対象読者を最初に示します。
• 前提条件を早めに明記します：ロール、権限、プランの制限、必要なデータ、ブラウザー／アプリ／バージョンに関する想定。
• 観察できる操作を優先します：ユーザーがクリックするもの、入力する内容、目にするもの、受け取るもの。
• 1 ページにつき主要な成果を 1 つにします。
• ロールごとに UI が異なる場合や別の手順がある場合など、分岐条件を明記します。
• タスクが成功したかどうかをユーザーが判断できるよう、成功の確認方法を示します。
• トラブルシューティングは汎用的な付録に埋もれさせず、タスクの近くに配置します。
• 混乱を招く移行箇所に意図的にスクリーンショットを使用し、クリックのたびには追加しません。
• 関連ドキュメントへのリンクを適切に配置します：FAQ → 完全なガイド、リリース関連ヘルプの更新 → 影響を受ける記事、スタートガイド → 次のタスク。

ステップ 7：保守と同期を確認する

最終確定の前に references/workflow-checklist.md と references/maintenance-signals.md を使用してください。

次の点を確認します。

1. ページの種類がユーザーの作業内容に合っている。
2. リスクのある手順より前に、前提条件とブロッカーが示されている。
3. スクリーンショットのプレースホルダーに妥当性があり、追跡可能である。
4. 同期を維持する必要がある関連ガイド、FAQ、リリース情報の更新、サポート用マクロが明記されている。
5. リクエストの範囲が変わった場合に、technical-writing、api-documentation、changelog-maintenance への引き継ぎが明確に保たれている。

ステップ 8：概要または完成した成果物を返す

本格的な草案作成の前に提示する概要の推奨形式：

# User Guide Writing Brief

## Mode
- Primary mode:
- Why it fits:
- Audience:
- Output shape:

## Source material used
- Product truth / UI evidence:
- Support or release signals:
- Assumptions / gaps:

## Planned artifact packet
1. main page
2. companion FAQ / refresh list / sync note

## Writing notes
- Key user outcome:
- Known blockers / branching conditions:
- Route-outs kept out of scope:

ユーザーがすでに完成した成果物を求めている場合は、選択したページまたはパケットを、対応する構成で直接作成します。

例

例 1：初回の成功を目指すオンボーディング

入力

新しいワークスペース管理者がチームを招待し、最初のプロジェクトを作成するためのスタートガイドを作成してください。

適切な出力の方向性

• モード：getting-started
• 出力形式：single-page
• 前提条件、手順の順序、成功の確認方法、次のステップを含める
• 内部向けの実装メモは対象外にする

例 2：リリースに合わせたドキュメントの更新

入力

エクスポートボタンがレポートのヘッダーに移動し、XLSX を選択できるのは管理者のみになったため、レポートのエクスポートに関するヘルプセンターの記事を更新してください。

適切な出力の方向性

• mode: release-help-update
• output shape: refresh-packet
• 変更された UI、ロールによる違い、スクリーンショットの更新、関連する補足ドキュメントを明示する
• リリースノートの要約は対象外とする

例 3：サポート回答から FAQ への変換

入力

繰り返し使っている請求に関するサポート回答を、ワークスペースのオーナー向けの短い FAQ にまとめてください。

適切な出力の方向性

• mode: faq
• output shape: single-page または guide-plus-faq
• 回答は短くし、必要に応じて詳細なタスクガイドにリンクする
• ロールやプランによる注意事項を早い段階で示す

例 4：開発者向けドキュメントとの境界

入力

外部の開発者向けに、公開されている webhook のクイックスタートと認証のトラブルシューティングページを更新してください。

適切な出力の方向性

• api-documentation に振り分ける
• 主な目的は公開されている開発者向け API ドキュメントであり、エンドユーザー向けの製品ガイドではないことを説明する

ベストプラクティス

1. 本文を書く前にページの種類を選びます。
2. 1 ページにつきユーザーの目標を 1 つ、1 回の実行につき主要なモードを 1 つにします。
3. 巨大なオールインワンガイドではなく、役立つ最小限のパケットを優先します。
4. ユーザーが行き詰まる前に、前提条件、権限、ブロッカーを提示します。
5. スクリーンショットは意図を持って使い、簡単に更新できるようにします。
6. サポート、検索、リリースのシグナルを使って、次に修正する箇所を決めます。
7. 内部ドキュメント、API ドキュメント、リリースノートは、スキルの対象範囲を無理に広げず、適切な場所に振り分けます。
8. 1 つのページで多くの作業を教え始めたら、目的が混在するドラフトをガイドのセットに分割します。

参考資料

• Diátaxis
• Google 開発者向けドキュメントのスタイルガイド
• Microsoft ライティング スタイル ガイド
• GitLab ドキュメントのワークフロー
• Write the Docs — Docs as Code