technical-document-authoring

技術文書の作成

ソフトウェアまたはウェブエンジニアリング分野の技術文書（設計文書、RFC、ADR、ランブック、README、API リファレンスなど）を作成またはレビューするときは、必ずこの機能を使用してください。同じ一連のルールに基づいて、次の2つのモードで動作します。

• 作成 — 読者が読み返さずに答えにたどり着けるよう、文書を起草し、構成を整えます。後から修正して整えるのではなく、最初から明快な構成を選びます。最初の文の前に読者を明示すること、文書の種類を1つに絞ること、要点を冒頭に置くことがその例です。
• レビュー — 草稿を読み、読者にかかる負担を考え、問題ごとに該当する箇所を示して指摘します。どちらのモードでも同じ基準を守ってください。自分で書いた草稿だからといって基準を緩めてはいけません。

対象は、チーム（エンジニア、レビュー担当者、運用担当者、システムを引き継ぐ人など）を読者とする文書の執筆技法です。読者の前提、用語、例の形式（コードブロック、ターミナルセッション、API の形式など）がこれに該当します。対象外は、ブログ記事、講演、ニュースレターなどの公開向け・個人向け文章、マーケティング文、フィクション、ソフトウェア以外の分野の学術論文、ソフトウェア製品以外のエンドユーザー向けドキュメントです。

この機能は、文書における平易な英語と用語レベルの一貫性を担当します（voice-tone-and-maintenance.md を参照）。別の機能がルールを担当する場合、この機能ではルールの文面を繰り返さず、トピックを示して委ねます。ただし、これらの委任は条件付きです。その機能を提供していないプロジェクトでは、該当する委任ルールは適用せず、代わりにこの機能のルールを適用してください。

• プロダクト要件または仕様作成の機能は、仕様のセクション構成、要件の表現、受け入れ基準を担当します。この機能は、その構成の中に書かれる文を担当します。
• エージェントスキル作成の機能は、スキル定義とその参照ファイル内の文章を担当し、ここに記載のルールに加えてスキル形式のルールを定めます。
• 会話形式のレポート作成の機能は、チャットの応答、進捗メモ、完了の概要、つまり文書ではなく返信を担当します。
• UI またはビジュアルデザインの機能は、インターフェースのアクセシビリティを担当します。この機能は、文書のアクセシビリティを担当します。

ガイドライン：

• プロジェクトで該当する機能が提供されている場合、必ずその機能の担当トピックにルールを委ね、その内容を重複して記述するのではなく要約してください。
• プロジェクトで提供されていない機能を前提とする委任は、違反ではなく適用外として扱い、代わりにこの機能独自のルールを適用してください。

この文書における「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」というキーワードは、RFC 2119 に記載された意味で解釈してください。

読者と文書の種類

読者と文書の種類では、以下について説明しています。

• 新しい文書の作成、または既存文書の再構成
• 執筆前に主な読者とその予備知識を特定すること
• 文書を単独で理解できるものとして扱うこと（ローカルファイル、作成途中の成果物、アクセス制限のあるリソースを参照しない）
• スコープ、前提条件、明確な対象外項目を冒頭に記載すること
• 4種類の文書（チュートリアル、ハウツー、リファレンス、解説）から1つを選び、混在させないこと
• 一般的なソフトウェアエンジニアリング文書の形式（RFC、ADR、ランブック、README、API リファレンス）を4種類に対応付けること
• 「文書に記載されていないものは、存在しない」というルールと、完全性に対するその意味

構成と流れ

structure-and-flow.mdでは、以下について説明しています。

• セクションの順序、見出しの作成または変更、回答を先に示すセクションの冒頭、読者に参照してほしいリンクの追加
• 詳細な説明の前に、回答／TL;DR／判断を示す
• 戦略や方針を示すドキュメントで変更の動機を説明する――「なぜ今なのか」に答え、重要な点を明示し、提案を候補として位置づける
• 読者が使う語彙を用いた見つけやすい見出しと、セクションの目的に合った形式
• 見出し階層のルール――レベルを飛ばさない、導入文なしで見出しを重ねない
• 流し読みしやすさ――内容がわかる見出し、段落の冒頭に重要な概念を置く、短い段落
• ドキュメント内で段階的に情報を開示する――説明の近くに手順を置き、簡単な内容から複雑な内容へ進む
• 内容がわかるリンクテキストと、参照しやすい安定したアンカー

文と単語の工夫

sentence-and-word-craft.mdでは、以下について説明しています。

• 文のレベルでドキュメントを編集する
• 能動態、二人称（「あなた」）、現在形を基本とする
• 1文につき1つの考えを述べる方法と、長い文を分割する方法
• 弱い動詞（be、have、make）を置き換え、冗長な表現を削る
• 図、コードブロック、リスト、表を紹介する場合を除き、コロンで始まる段落ラベル（「原則：」「ルール：」）を避ける
• 新しい用語は一度だけ定義し、同じ用語を一貫して使う――類義語に置き換えない
• 頭字語のルール（初出時に正式名称を書く。大幅に短くなり、繰り返し使う場合にのみ略す）
• 曖昧な代名詞（it、this、that、they）を避け、名詞を繰り返すか、指示対象の近くに置く

リスト、表、コード例

lists-tables-and-code.mdでは、以下について説明しています。

• 箇条書き、番号付きリスト、表、文章のどれを使うか
• リスト項目間で文法、大小文字、句読点を統一する
• 番号付きの手順は命令形の動詞で始める
• コロンで終わる導入文でリストや表を紹介する
• コード例のルール――最小限で、実行可能で、現実的な例とし、周囲に文脈を添える
• インラインコードの書式、UI 要素の書式、図／表のキャプション
• Mermaidで図を作成する――適切な図の種類を選び、```mermaidのフェンス付きブロックに埋め込み、キャプションと文章による要約を添える

文体、トーン、メンテナンス

voice-tone-and-maintenance.mdでは、以下について説明しています。

• 読者を責めない、会話的でありながらプロフェッショナルな文体
• 包括的な言葉遣いと、ジェンダーに中立な表現
• グローバル化――慣用表現、スポーツ／文化的な比喩、曖昧な日付形式を避ける
• 専門用語のレベルをCEFR C1に保つ（C2を超える語、C2の語、C1の語のうち、難解な語を置き換える表を含む）ことで、母語話者でない読者も辞書なしで読めるようにする
• アクセシビリティ――代替テキスト、内容がわかるリンクテキスト、色だけに頼らないこと
• メンテナンス――完全性より最新性を重視する、ARID（ある程度の繰り返しを受け入れる）、信頼できる唯一の情報源
• 自己校正――複数回推敲する、声に出して読む、見直しの前に休憩を取る、2回目の推敲で削る