---
name: technical-writing
description: "技術文書を、読み手が 1 回で理解して行動できるように書く・レビューする。文書のモード選択（チュートリアル、ハウツー、リファレンス、解説）、手順の書き方、一文一義、誤読の余地の排除、用語統一、見出し・リンク・リストの規約、PR 説明とコミットメッセージを扱う。AI 臭の除去は anti-ai-writing、Markdown のリンク・構造の検査は markdown-check が担当する。Use when: README、設計書、RFC、手順書、リファレンス、PR 説明、コミットメッセージを書く・直す・レビューするとき。Triggers: technical writing、テクニカルライティング、技術文書、手順書、分かりにくい文書、ドキュメントレビュー"
---

# Technical writing

疲れたエンジニアが 1 回読んで理解できる文章を書きます。文書のモードを決め、手順を書き、文を組み立て、誤読の余地を消します。

次の 3 つは、すべての規則より優先します。

- 働いていない語は削ります。「ということになります」は「です」にします。
- 平易な語を使います。「当該ファイル」は名前で指し、「〜に際して」は「〜するとき」にします。
- 規則に従うと文が悪くなるときは、別の形に直すか、そのまま残します。規則を守っても機械が書いたように読める文は、失敗です。

コードベースが用語集です。実在するシンボル、ファイル、フラグ、コマンドの名前を、言い換えや説明に置き換えずにそのまま書きます。造語は作りません。パターン名は、初出で意味を書いたときだけ使います。

## 進め方

1. 読者、目的、文書のモードを決めます。モードを決められないときは、書く前にここで止まります。
2. モードの規則に沿って書きます。手順は「手順の書き方」、文は「文の設計」に従います。
3. 文体と語彙の AI 臭は `anti-ai-writing` で検査して直します。Markdown のリンクと構造は `markdown-check` で検査します。このスキルはどちらも判断しません。
4. 通読して、読者が 1 回で次の行動を取れるか確かめます。

診断だけを求められたときは、指摘と修正案を返し、対象を書き換えません。

## モードを先に決める

1 つの文書は 1 つのモードにします。次の 2 つの問いで決めます。

- 内容は行動のためか、理解のためか。
- 読者は学習中か、仕事中か。

| モード | 判定 | 書くこと | 書かないこと |
|:--|:--|:--|:--|
| チュートリアル | 行動 + 学習 | 冒頭で何を作るかを書きます。各手順で見える結果と、期待する出力を書きます。説明は 1 文とリンクに留めます。 | 背景、網羅、分岐 |
| ハウツー | 行動 + 仕事 | 読者が持つ課題の解き方を書きます。能力を前提にし、行動だけを書きます。「Xしたい場合は、Yします」の分岐は書いてかまいません。題名は「〜する方法」とタスクで付けます。 | 教える文、背景、意見 |
| リファレンス | 理解 + 仕事 | 事実、オプション、制限、エラーを、言い切って書きます。説明する対象の構造に合わせ、可能ならコードから生成します。 | 指示、説得、意見、ぼかし |
| 解説 | 理解 + 学習 | 設計判断、経緯、制約、代替案を、実在する「なぜ」に結び付けて書きます。意見は、ここにだけ書きます。 | 手順 |

モードを混ぜません。チュートリアルにリファレンスの表を入れたり、リファレンスに手取り足取りの説明を入れたり、ハウツーで議論したりしません。分けて、リンクでつなぎます。

## 手順の書き方

- 1 文に 1 つの動作を書きます。2 つの動作は文を分けて番号を振ります。
- 条件は動作の前に書きます。「削除するには、[削除] を選択します」「失敗した場合は、再実行します」のようにします。
- 警告は、守らせたい手順の前に置きます。`> [!WARNING]` などで目立たせ、手順の後ろには書きません。
- 共通のケースを先に、例外を後に書きます。
- 1 つの動作には 1 つの動詞を使い、文書全体で揃えます。「起動する」と「立ち上げる」を混ぜません。
- 手順に「簡単に」「すぐに」「だけで」「単に」を書きません。簡単なら、読者はこの手順を読んでいません。
- 文末は「〜します」か「〜してください」のどちらかに統一します。既存の文書があれば、それに合わせます。
- 件数やファイル構成を書くときは、書いた時点で正しい内容にします。再生成するコマンドを添えるか、書きません。

## 文の設計

### 一文一義

- 1 文には 1 つの考えを書きます。手順の文は 60 字、それ以外は 100 字を超えたら分けられないか確かめます。数値は目安で、1 つの考えを運ぶ長い文は残します。
- 動作主を主語にします。「検証される」は「コンパイラが検証します」に、「再実行される」は「スケジューラーが再実行します」にします。動作主が不明、または重要でないときだけ受け身にします。
- 前提と結論の間に、読者が補う論理の飛躍を残しません。

### 誤読の余地を消す

読み方が 2 通りある文を残しません。次の型を探します。

| 型 | 直す前 | 直した後 |
|:--|:--|:--|
| 指示語が複数のものを指す | 「キャッシュを削除して再ビルドします。これは時間がかかります。」 | 「再ビルドには時間がかかります。」 節や文を「これ」「それ」で受けず、名詞を繰り返します。 |
| 修飾語の係り先が 2 通り | 「古いログと設定ファイルを削除します。」 | 「古いログと古い設定ファイルを削除します。」または「設定ファイルと古いログを削除します。」 |
| 「の」が連なる | 「設定ファイルの読み込みの失敗の通知」 | 「設定ファイルの読み込みに失敗したことを通知します。」 |
| 「だけ」「のみ」「も」「しか」の位置 | 「管理者だけにメールを送ります。」 | 「管理者にだけメールを送ります。」または「管理者にメールだけを送ります。」 限定する語の直後に置きます。 |
| 動作主の省略 | 「失敗すると再実行されます。」 | 「ジョブが失敗すると、スケジューラーがジョブを再実行します。」 |
| 並列の範囲 | 「ロールが管理者または編集者で、有効なトークンを持つ場合」 | 「有効なトークンを持ち、かつロールが管理者か編集者のどちらかである場合」 条件が 3 つ以上なら箇条書きにします。 |
| 記号で省略 | 「AND/OR」「A/B」「A→B」 | 「AとBの両方、またはどちらか一方」「AまたはB」「AからBへ」 |
| 濁した列挙と程度 | 「ログなどを確認します。」「適切に設定します。」 | 見るものをすべて書きます。列挙が一部なら、冒頭で「主なものを挙げます」と述べます。「適切」は基準を書きます。 |

### 用語を揃える

- 1 つの概念には 1 つの名前を付け、1 つの名前には 1 つの意味だけを持たせます。初出で定義し、以降は同じ語を使います。
- 表記ゆれを揃えます。長音（ユーザー、ユーザ）、送り仮名、漢字とかな（できる、出来る）、英字の大文字小文字（GitHub、Github）、全角と半角が対象です。製品名とサービス名は公式の表記にします。
- 既存の文書に表記があれば、それに合わせます。変更していない箇所の用語は変えません。

### 見出し・リンク・リスト

- 見出しは要点を述べます。「モード」ではなく「モードを先に決める」にします。タスクの見出しは動詞句（「インスタンスを作成する」）、概念の見出しは名詞句にします。h1 は 1 つにし、レベルを飛ばしません。
- リンクの文言は、行き先が分かる語にします。「こちら」「ここ」にしません。リンク先に飛ばすより、その場に 1 文の文脈を書くほうを優先します。
- 順序のある手順は番号付きリスト、それ以外は箇条書きにします。リストの前は、完結した文で受けます。項目の文末と粒度を揃えます。
- コード、パス、コマンド、フラグはコードフォントにします。UI の名称は太字にします。

## 対象別の注意

- PR 説明は、レビュアーが 1 分で読める要約にします。何を、なぜ、どう確かめたか、レビューで見てほしい点を書きます。ログ、SHA の一覧、メトリクスの表は貼らずにリンクします。
- コミットメッセージにも、モード以外の規則を適用します。リポジトリにコミット規約があれば従います。
- 製品の画面に出る文言は、文書ではありません。製品のコピーガイドに従います。

## 例

直す前の文です。

> budget.json のスクリプトパラメータの設定により、インポート上限チェックの実行が行われます。なお、--write を付けて実行した場合、それが更新されるため、上限を下げるとき以外は避けることが望ましいです。

直した後の文です。

> `budget.mjs` は `budget.json` から上限値を読み込み、protobuf をインポートしているファイルの数を数えます。数が上限を超えると、CI が失敗します。`budget.mjs --write` は上限値を書き換えるので、上限を下げるときだけ実行してください。

直した点は、「実行が行われます」を動作主のいる文にしたこと、「それ」を「上限値」に戻したこと、「避けることが望ましい」を実行してよい条件に変えたこと、実在のファイル名とコマンド名をコードフォントで書いたことです。

## 他のスキルとの分担

| 確かめたいこと | スキル |
|:--|:--|
| 文書の種類、手順、文の設計、用語の一貫性 | このスキル |
| AI にありがちな表現、構成、リズム | `anti-ai-writing` |
| リンク切れ、アンカー、見出しのレベル、表の構造 | `markdown-check` |

## 出典

- [Diátaxis](https://diataxis.fr/): 文書の 4 モード。
- [Google developer documentation style guide](https://developers.google.com/style): 読み手に向けて書く文の規則。
- [ASD-STE100](https://www.asd-ste100.org/): 1 文 1 指示、1 語 1 義の考え方。
- [Microsoft 日本語スタイルガイド](https://learn.microsoft.com/ja-jp/style-guide/welcome/): 日本語の表記と文体の参考。
- [pstack の technical-writing](https://github.com/cursor/plugins/blob/main/pstack/skills/technical-writing/SKILL.md): 4 層の構成。このスキルは、その考え方を日本語向けに組み直したものです。