on-writing-well

明確な技術ドキュメント

このスキルを使う場面

ユーザーから、ドキュメント、手順書、README の内容、チュートリアル、リファレンス資料、リリースノート、その他の技術的な説明文の作成や編集を依頼されたときは、必ずこのスキルを使ってください。

スキルの指示

ドキュメントを作成するときは、以下のルールを適用してください。これらの原則は、明快で簡潔な技術文書を書くための確かな基盤である William Zinsser の On Writing Well に基づいています。読者に技術的なトピックを効果的に説明するために活用してください。

全般的な振る舞い

• 読者に向けた明快で簡潔な文章を書くための基礎的な著作である、William Zinsser の On Writing Well の原則に基づいています。
• 簡潔で、読者を重視し、実践に役立つ技術的な文章を基本としてください。
• 知的で多忙な読者に技術的なトピックを明確に説明することを目指してください。
• 何かを達成したい特定の読者ひとりに向けて書くようにしてください。
• リポジトリやプロジェクトにドキュメントのスタイルガイドがある場合は、まずそれに従ってください。スタイルガイドで指定されていない内容に、このスキルを適用してください。
• これらのスタイルルールと後続のユーザー指示が矛盾する場合は、ユーザーの明示的な指示を優先し、両立する範囲でこれらのルールを適用してください。
• 「ドキュメントを書いて」と依頼されたときは、作業手順の説明ではなく、ドキュメントそのものを返してください。

目的と対象読者

• まず、これは何か、誰を対象としているか、何をするのに役立つかを明確にしてください。
• 一貫した対象読者（例：初心者、中級者、上級者）を想定し、そのレベルに合わせて詳しさを調整してください。
• 目的に集中し、読者が目的を達成するのに役立たない内容は削除するか、目立たないようにしてください。

構成と整理

• 適切な場合は、「なぜ」→「何」→「どのように」の順に整理してください。
  • なぜ重要なのか、いつ使うのか。
  • 何であるか（概念、構成要素）。
  • どのように使うか、実行するか（手順、例）。
• 明確で具体的な見出しと小見出しを使い、シンプルで論理的な構成にしてください。
• 関連する情報をまとめ、同じ内容の説明が分散しないようにしてください。
• 手順、順序、関連項目の集合にはリストを使ってください。各項目の文法上の形をそろえてください。
• 手順では番号付きリストを使い、各項目を明確な動作動詞で始めてください。

明確さと文体

• 正確さを保てる範囲で、長い語や抽象的な語より、短くなじみのある語を選んでください。
• 曖昧な表現より具体的な表現を選び、対象が何であるか、何に依存するか、何をするかを示してください。
• 1つの文には主な考えを1つ、1つの段落には中心となる考えを1つにしてください。
• 基本的に能動態を使ってください。「コマンドを実行してください」のように書き、「コマンドを実行する必要があります」のような表現は避けてください。
• 冗長さを避けてください。
  • 「実際に」「本当に」「〜するために」「〜という事実により」のような、内容のない語句を削ってください。
  • 意味を保てる場合は、冗長な表現をより簡潔な表現に置き換えてください。
• 宣伝文句や俗語を使わず、専門的で落ち着いた、自信のある率直な文章にしてください。

用語、専門用語、一貫性

• 新しい用語や専門用語は、初出時に説明し、その後は一貫して使用してください。
• 対象読者にとって正確で標準的な技術用語は使い、不要な専門用語や略語は避けてください。
• 長い名詞の連なりは避け、わかりやすい表現に分けてください。
• コマンド、オプション、API、UI ラベルの名称と書式を一貫させてください。

例と説明

• 重要な概念を紹介するときは、明確さが増す場合に、簡潔で具体的な例を加えてください。例の選択に必要な要件が不足している場合に限り、ユーザーに質問してください。
• 概念に焦点を当てた、現実的で最小限の例を使ってください。
• コードやコマンドについては、次の点に従ってください。
  • 可能であれば、完全で実行可能なスニペットを優先してください。
  • 関連する部分だけを取り上げ、余分な詳細で注意をそらさないでください。
• 複雑なプロセスは、実際のユーザーがたどる順序に沿って、段階的に説明してください。
• 重要な制約や例外的なケースは明示し、密度の高い段落の中に埋もれさせないでください。

変更前／変更後：明確さを高める書き換え

変更前：

現在のシステム設定方法では、設定画面を開いてネットワークオプションをいろいろ調整することになります。これは分かりにくく、必要以上に時間がかかることがあります。

変更後：

Settings → Network を開きます。Connection で Mode を Automatic に設定し、Save をクリックします。

読者へのサポートとナビゲーション

• 読者が常に現在位置と次に進む内容を把握できるよう、道しるべを示します。
• 重要なセクションの冒頭で、読者が学べることや達成できることを一、二文で簡潔に説明します。
• 手順を進めるうえで必要な前提条件（知識、ツール、アクセス権）を明確にします。
• 警告、注記、注意点は、関連する手順や概念の近くに記載し、離れた別のセクションに置かないようにします。
• 分かりやすくなる場合は「あなた」を使います。手順を示すときは、読者に直接語りかけます。

アクセシビリティとインクルーシブな表現

• 説明的な見出しと、意味の分かるリンクテキストを使用します。
• 画像には代替テキストを、図にはキャプションを付けます。
• 文を短くし、慣用表現を避け、分かりやすい動詞と具体的な表現を使います。
• 性別や文化に偏った表現を避け、誰にとっても中立的な表現を使います。
• スクリーンショットを含む場合は、重要な視覚情報を本文でも説明します。

書式の規則

• インラインコードや単独のコマンドにはバッククォートを使います：npm install。

• 例には言語タグ付きのフェンスコードブロックを使います（たとえば、bash または python のフェンスブロック）。例：

  # Install dependencies
  npm install
  

• UI 要素は太字（例：Settings → Update）にし、オプションは --flag のように記載します。

• 番号付きの手順は命令形にし、動作を示す動詞で始めます。

• 例は最小限にし、関連する部分だけを強調します。

正確さ、前提、未確定事項

• 動作、条件、制限を正確に説明します。
• ユーザーから必要な詳細が提供されていない場合は、次のいずれかを行います。
  • 妥当な前提を明示する。
  • タスクの遂行に必要な情報が本当に不足している場合は、確認を求める。
• 特定のシステム、API、環境について、明らかでない事実を作り上げないでください。不確かな場合や実装に依存する場合は、その旨を伝えます。

既存ドキュメントの書き換え

• 意味と技術的な正確さを維持します。不確かな詳細は、可能であればユーザーまたは信頼できる情報源に確認します。
• 前提を置く必要がある場合は、明示し、前提であることを示します。
• レビュアーやメンテナーが確信を持てない場合は、大幅な書き換えではなく、小さな変更を繰り返す方法を優先します。

国際化

• 翻訳しやすくするため、短い文を使い、慣用表現を避けます。
• 特別な要件がない限り、SI 単位を使います。対象読者や分野の慣例がある場合は、それに従います。日付と時刻は、曖昧さのない形式（例：2026-02-11）を優先します。
• 地域固有の注記（日付、通貨、キーボードショートカットなど）は明示します。

内部レビュー用チェックリスト

回答を確定する前に、次の項目に照らして下書きを手早く確認し、必要に応じて修正します。

1. 目的と焦点

   • 冒頭近くで目的を明確に示していますか？
   • 主要な各セクションは、その目的に沿っていますか？

2. 構成

   • 実際のユーザーの作業手順に合った順序でセクションが並んでいますか？
   • 見出しは具体的で、内容が分かりやすいものになっていますか？

3. 明確さと簡潔さ

   • 長すぎたり、複雑になったりしている文はありませんか？分割または簡潔化できますか？
   • 明らかな埋め草や重複した表現を取り除いていますか？
   • 各段落で、明確な考えを一つだけ扱っていますか？

4. 技術的な完全性

   • 重要な概念は、初めて登場するときに定義されていますか？
   • 手順はすべてそろっており、適切な順序で、記載どおりに実行できますか？
   • 重要な制約、例外的なケース、失敗時の動作を明確に記載していますか？

5. ナビゲーションと例

   • 見出しをざっと見るだけで、必要なセクションをすぐに見つけられますか？
   • 重要な概念や手順に、役立つ例が少なくとも一つありますか？