writing-web-documentation

Web ドキュメントの作成

ユーザーが、単に「コードの周りに文章を少し添える」のではなく、Web プロジェクト向けの優れた技術ドキュメントを求めている場合に、このスキルを使います。目指すのは、読み始めやすく、要点をつかみやすく、信頼でき、保守しやすいドキュメントです。

優れたドキュメントは、製品情報を並べただけのものではありません。特定の目的を持つ読者を、製品の中へ導く道筋です。

このスキルが重視すること

1. すばやく最初の成功にたどり着く 新しい読者が、すぐに動作する結果を得られるようにします。

2. 目的に応じた明確な案内 製品を学ぶ初心者と、あるオプションを確認するエキスパートが、同じページで苦労せずに済むようにします。

3. 曖昧さの排除 コマンド、ファイル名、バージョン、前提条件、期待される結果、失敗時の状態を明確にします。

4. ひと目で把握できること 多忙な開発者は、読み込む前にざっと目を通します。見出し、導入文、リスト、表、コードブロックで、ページ全体をひと目で把握できるようにします。

5. 保守性 ドキュメントが古くなりにくく、コードの変更に合わせて更新しやすく、古い情報が明らかになるようにします。

目的ではないこと

次のことを重視しないでください。

• 誇大な表現
• マーケティング用の言葉
• すべてのページでの網羅的な背景説明
• 最初のドキュメントですべての対応パターンを示すこと
• 気の利いた文章
• 説明がほとんどない膨大なコードの羅列

最初に決めること：これはどの種類のページか？

ページの種類を決める前に、執筆を始めてはいけません。ページの種類を混同しないでください。

README またはドキュメントのランディングページ

概要と案内に使います。

• 答える内容：これは何か？誰向けか？どこから始めればよいか？
• 簡潔にまとめます。
• 詳細は下位ページに移します。

クイックスタート

最短の手順で、正常に動作する結果を得るために使います。

• 手順は1つにします。
• 主な環境は1つにします。
• 分岐は最小限にします。
• 前提条件と、目に見える成功状態を明確にします。

チュートリアル

実際に手を動かしながら学ぶために使います。

• 読者が意味のあるものを作成します。
• 確認ポイントと振り返りを含めます。
• 学ぶのに十分な説明を加えますが、百科事典のような網羅性は目指しません。

ハウツーガイド

具体的な問題を1つ解決するために使います。

• 読者が基本をすでに理解していることを前提とします。
• 背景理論ではなく、目的の達成に焦点を当てます。

リファレンス

正確で事実に基づく質問に答えるために使います。

• 構文、オプション、デフォルト値、パラメーター、戻り値、イベント、エラー、制限、互換性。
• 客観的で、網羅的で、要点をつかみやすい内容にします。

解説／概念ページ

メンタルモデルを構築するために使います。

• システムがこのように動作する理由。
• アーキテクチャ、トレードオフ、不変条件、判断基準。
• タスク別のドキュメントやリファレンスドキュメントにリンクします。

トラブルシューティングページ

症状から問題を診断するために使います。

• 症状 -> 考えられる原因 -> 対処方法 -> 確認 -> 再発防止。

移行ガイド

バージョン、API、アーキテクチャが変更された場合に使います。

• どのような破壊的変更があるかを明示します。
• 変更前と変更後を示します。
• 安全に進めるための手順を示します。
• 必要に応じて、ロールバック方法を含めます。

標準的なワークフロー

ユーザーからより限定的な依頼がない限り、このワークフローに従います。

1）読者と目的を特定する

次の内容を推測するか、明示します。

• 読者の種類：初心者、経験豊富なユーザー、メンテナー、インテグレーター、API 利用者、プラットフォームエンジニア
• タスク：学習、セットアップ、統合、カスタマイズ、デバッグ、移行、デプロイ、コントリビュート
• 環境：フレームワーク、ランタイム、パッケージマネージャー、OS、ブラウザー、ホスティング先
• 成功状態：読み終えた後に、読者が何をできるようになるべきか

重要な情報が欠けていても、いつまでも作業を止めてはいけません。妥当な範囲で最も限定的な前提を置き、それを明確に示します。

2）文章を書く前に事実を洗い出す

古くなりやすい次の情報を収集します。

• パッケージ名
• インストールコマンド
• ランタイムとフレームワークのバージョン
• 対応ブラウザーまたは環境
• 環境変数
• URL、エンドポイント、ポート、コールバックパス
• 権限、認証要件、キー、トークン
• ビルド、テスト、デプロイのコマンド
• 破壊的変更や制約

事実を確認できない場合は、作り上げないでください。明示的なプレースホルダーまたは前提を使います。

3) まずページの骨組みを作成する

本文を書く前に、ページに必要なセクションを正確に含む骨組みを作成します。

推奨する順序：

• 背景
• 前提条件
• 手順または本文
• 確認／期待される結果
• 次のステップ／関連ページ

4) 最初の実行を成功させることを優先する

すべてのタスクページで、読者ができるだけ早く一度成功できるようにします。

そのために、以下を実践します。

• 最短の実行手順を最初に示す
• 分岐を最小限にする
• 高度なオプションは後回しにする
• プロジェクトが複数の主要な開始方法を本当にサポートしている場合を除き、パッケージマネージャーとフレームワークはそれぞれ一つを優先する
• 成功時の状態を示す

5) 実行可能な例を作る

例は、コピーして貼り付けて実行できるか、簡単に応用できるものにします。

• 実際のファイル名と現実的なディレクトリを使用する
• コードフェンスに言語を指定する
• 例は最小限かつ完全なものにする
• あいまいさを解消する場合にのみコメントを追加する
• コマンドが破壊的または課金対象となる場合は、事前に警告する
• 重要な手順の後に、期待される出力または目に見える結果を示す

6) 文章を引き締める

下書きができたら、次の作業を行います。

• 導入を短くする
• 長い段落を分割する
• 曖昧な見出しをタスクに基づく見出しに変える
• 重複した説明を削除する
• 理論的な内容は手順ページから移動する
• 詳細はランディングページから移動する

7) レビューチェックリストを実行する

提出前に assets/review-checklist.md を使用します。

参考ファイル

現在のタスクに応じて、必要なときに次のファイルを読み込みます。

参考資料	目的
references/house-style.md	文体、文のスタイル、見出し、長さの目安、ページタイプのパターン
references/web-project-rules.md	Web プロジェクトのチェックリスト、コード例のルール、アンチパターン、アクセシビリティ、ドキュメントをコードとして扱う方法
references/research-notes.md	優れたドキュメントサイトやスタイルガイドから得た調査内容の統合

すべてのファイルを一度に読み込まないでください。 現在のタスクに関連するものだけを読み込みます。

一般的なタスクモードでの応答方法

ページをゼロから作成するよう求められた場合

次の内容を提示します。

1. 適切なページタイプ
2. 洗練された Markdown の下書き
3. 重要な事実が不明な場合は、前提を明確に示す

既存のドキュメントの改善を求められた場合

次の順に作業します。

1. 現在のページタイプを特定する
2. 混在している形式を取り除く
3. 構成を引き締める
4. 明瞭さを重視して書き直す
5. 技術的な意味を維持する
6. 事実の不足や古くなるリスクを指摘する

ドキュメントのレビューを求められた場合

次の内容を返します。

• ページタイプ
• 優先度順に並べた主な問題点
• 正確な書き換え案
• 不足しているセクション
• 古くなるリスクや信頼性に関する問題

ドキュメントサイトの設計を求められた場合

次の内容を返します。

• 対象読者の区分
• 開始地点
• 必要なページタイプ
• サイトマップ
• 作成の優先順位
• 不足事項とリスク

このスキル内のファイル

• assets/documentation-brief-template.md — 執筆前に情報を収集します
• assets/docs-ia-template.md — ドキュメントサイトまたはセクションを構成します
• assets/docs-home-template.md — ランディングページのひな形
• assets/readme-template.md — README のひな形
• assets/quickstart-template.md — 最短で使い始めるためのセットアップガイド
• assets/tutorial-template.md — 実践しながら学ぶためのガイド
• assets/how-to-template.md — タスクに特化したガイド
• assets/reference-template.md — API／リファレンスのひな形
• assets/explanation-template.md — メンタルモデルを説明するページ
• assets/troubleshooting-template.md — 症状から始めるトラブルシューティング
• assets/migration-guide-template.md — アップグレード／移行ページ
• assets/review-checklist.md — 最終品質チェック
• references/house-style.md — 文体、長さの目安、ページタイプごとのパターン
• references/web-project-rules.md — Web プロジェクトのチェックリスト、コードのルール、アンチパターン
• references/research-notes.md — これらのルールが存在する理由

最後に

優れたドキュメントページが読みやすく感じられるのは、書き手が読者のために何百もの細やかな選択を重ねているからです。

• このページに何を含めるか
• 何を含めないか
• 何を先に説明するか
• 何を削るか
• 何を確認するか
• 何を説明するか
• 何を後回しにするか

こうした選択を、意識して行ってください。