technical-writing

テクニカルライティング

疲れているエンジニアが一読で理解できるように書きます。4 つのレイヤーをすべて適用してください。

レイヤーに優先するルールが 3 つあります。

• 役に立たない言葉はすべて削ります。 その言葉がなくても文が成り立つなら、その言葉は不要です。「In order to」は「to」で十分です。「It is important to note that」は何も伝えていません。
• 短く、日常的な言葉を使います。 「utilize」ではなく「use」、「facilitate」ではなく「help」、「perform」ではなく「do」を使います。長い言葉を使うなら、その長さに見合う正確さが必要です。
• ルールに従うことで文が悪くなるなら、別の方法で直すか、そのままにします。 すべてのルールに従っていても、機械が書いたように聞こえる文は失敗です。

コードベースが語彙の基準です。同義語や説明ではなく、実際のシンボル名、ファイル名、フラグ名、コマンド名を使います。

専門用語をでっち上げないでください。開発者が口にする言葉を使います。「evacuate」「ratchet」「endgame」ではなく、「move」「delete」「減る一方の予算」と書きます。名前の付いたパターンを使ってよいのは、その文書で最初に意味を説明する場合です。新たな問題語とその置き換えを、返信の中で unslop の抽象的な比喩に関するルールへの追加案として、差分とともに提案してください。そのスキル自体は編集しないでください。

リズムに変化をつける

すべてのレイヤーに従っていても、文書が機械の書いたように読めることがあります。文がどれも短く、見解がなく、具体性もない状態です。

• 意図して文の長さに変化をつけます。短い文で要点を伝え、長い文で条件や結果を含む事実を伝えます。
• 1 文に 1 つの考えを入れることは、すべての文を同じ長さにすることではありません。2 つの考えを含む文は分けます。1 つの考えを伝える長い文はそのままにします。
• 文書のモードで許されるなら、見解を示します。解説ではトレードオフを検討し、長所と短所を並べるだけでなく、それをどう評価するかを述べます。リファレンスは淡々と書きます。
• 無機質な表現より具体的な表現を選びます。「スキーマの変更は問題を起こすことがあります」ではなく、「カラム名を変更するとビルドに失敗します」と書きます。

まずモードを選ぶ（Diátaxis）

1 つの文書には 1 つのモードを使います。2 つの質問で決めます。内容は行動（実行）と理解（思考）のどちらに関わるか、また学習と作業のどちらに役立つかです。

• 行動＋学習：チュートリアル。
• 行動＋作業：ハウツー。
• 理解＋作業：リファレンス。
• 理解＋学習：解説。

この指針は文書全体にも、1 文にも適用できます。

チュートリアル：実践しながら学ぶ。 学習者を成功させるのはあなたの役目です。学習者が「何を学ぶか」ではなく、何を作るかを最初に伝えます。手順ごとに、早い段階から目に見える成果を出します。期待される出力、プロンプトの変化、ログの行など、何が見えるはずかを伝えます。説明は 1 つの節とリンクだけに絞ります。具体的に書きます。「まず x を実行します。次に y を実行します」のように、私たちを主語にして指示します。

ハウツー：目標を達成する手順。 機械が実行できる操作ではなく、人が抱える問題を解決します。読者の知識を前提とし、説明は省きます。行動だけを書きます。脱線、背景説明、完全性のためだけの網羅は避けます。代わりにリンクします。選択肢や判断の余地を残します。「x が必要なら、y を実行します」のように書きます。ガイドのタイトルは作業内容にします。「レーダーアレイを校正する方法」とし、「レーダーアレイの校正」とはしません。

リファレンス：参照用の事実。 説明だけを記載します。指示、説得、意見は含めません。簡潔かつ網羅的に、断定して書きます。事実、選択肢、制限、エラーを、曖昧にせず示します。読者がコードとドキュメントを一緒にたどれるよう、説明対象の構造に合わせます。読者が期待する場所に情報を置きます。可能であれば、コードから生成します。

解説：仕組みと理由を理解する。 範囲を絞ったトピックを、製品から離れて読んでも理解できるように書きます。各タイトルの前に「〜について」を補っても自然に読めるようにします。現実にある「なぜ」という問いを軸にします。設計上の判断、経緯、制約、代替案などの背景を示します。意見を述べてよいのはこのモードだけです。

モードを混ぜないでください。チュートリアルにリファレンス表を入れず、リファレンスで手取り足取り教えず、ハウツーで議論をしないでください。文書を分け、互いにリンクします。

読者に向けて文章を書く（Google の開発者向けスタイル）

• 読者に「あなた」と呼びかけ、現在形で書きます。本当に後で起こることに限り、「will」を使います。
• 誰が何をするのかを明確にします。「コンパイラーが確認する」と書き、「確認される」とは書きません。行為者が不明、または重要でない場合に限り、受動態を使えます。
• 指示は命令形で書きます。「Submit をクリックします。」と書きます。事実はそのまま述べます。「実行する必要があります」とは書きません。
• 条件を指示より先に置きます。「ドキュメントを削除するには、Delete をクリックします。」
• よくあるケースを先に書きます。例外は後に書きます。
• 知識のある友人のような語り口にします。流行語や比喩表現は使いません。指示に「お願いします」を使わず、手順では「単に」、「簡単に」、「すばやく」を決して使いません。簡単なことなら、読者はここに来ていないはずです。
• 前置きで予告しません（「今後まもなくサポートする予定です」など）。連続する文を同じ語句で始めません。
• リンク先が分かる語句でリンクします。ページのタイトルか、簡潔な説明を使います。「ここをクリック」は使いません。ページ外のリンクより、ページ内で文脈を説明する文を優先します。
• 見出しには、単なる話題ではなく要点を示します（「モード」ではなく「先にモードを選択する」）。文頭のみ大文字にします。タスクの見出しは動詞句だけにします（「インスタンスを作成する」）。概念の見出しは名詞句にします。ページ内の h1 は 1 つだけにし、見出しレベルを飛ばしません。
• 手順には番号付きリストを使い、それ以外には箇条書きを使います。リストの前に完結した文を置きます。各項目の形式をそろえます。
• コードにはコードフォントを使います。UI 要素は太字にします。並列する語句の前にはシリアルカンマを使います。「など」は使わず、リストが一部のみであることを先に伝えます。

文を一度に一つずつ読み取れるようにする（STE ルール）

• 指示は 1 文につき 1 つにします。それ以外の文も、1 文につき 1 つの考えだけを述べます。
• 20 語程度を超える指示文は分割します。それ以外の文は 25 語程度を超えたら分割します。
• 警告や条件は、それが適用される手順より先に置きます。「熱い油が皮膚に触れると、けがをするおそれがあります。」
• 「the」と「a」を省略しません。「バックアップファイルを削除する」では 2 通りに読めます。「そのバックアップファイルを削除する」なら 1 通りに読めます。
• 各単語には 1 つの意味と役割だけを持たせ、その使い方を統一します。「確認する」を調べる意味で使うなら、抑制する意味では使いません。
• それぞれの動作には 1 つの単語を選び、使い方を統一します。「開始する」と「始動する」を混在させず、「開始する」に統一します。
• 手順は直接的な命令形で書きます。説明口調や受動態は使いません。「コンポーネントをインストールします」と書き、「コンポーネントをインストールする必要があります」とは書きません。
• 可能な限り「-ing」形の単語を避けます。

どちらにも読める文をなくす（グローバル英語）

• 「only」や「not」などの語は、意味を変える語のすぐそばに置きます。「only fails on growth」と「fails only on growth」では意味が異なります。
• 長い名詞の連なりを分割します。「the proto import budget check script」は「proto のインポート予算を確認するスクリプト」とします。
• 「it」、「they」、「this」が何を指すのかを明確にします。迷ったら名詞を繰り返します。「this」や「which」で文全体を指すことは避けます。
• 動詞を省略しません。「フェーズ 1 ではコンバーターを移動し、フェーズ 2 ではランタイムを移動します」と書きます。「フェーズ 2 ではランタイム」として、動詞を省略してはいけません。
• 構造を示す小さな語も省略しません。「スイッチがオフになっていることを確認します」の「こと」などを残します。文字数を減らすために明確さを犠牲にしません。
• 並列する項目を誤読されるおそれがある場合は、冠詞を繰り返します。2 つのものを指す場合は、「クライアントとホスト」ではなく「そのクライアントとそのホスト」とします。
• 文の中で「and」や「or」が何を結び付けているのか、明確にします。「both...and」、「either...or」、「if...then」を使うと、曖昧さを避けられます。
• セミコロンではなくピリオドを使います。ダッシュは新しい文に置き換えます。
• 括弧内の文は、文法的に完結させるか、独立した文にします。単語の複数形を「(s)」で表しません。
• スラッシュは使いません。「a/b」や「and/or」ではなく、「a、b、またはその両方」と書きます。
• 同じものは、どこでも同じ名前で呼びます。1 つのものを「ゲート」、「ラチェット」、「予算チェック」と呼び分けると、3 つのものがあるように読者に伝わります。変更していない用語を変更しません。
• 慣用句、口語表現、ラテン語の略語、比喩表現は使いません。

文体とリポジトリ固有のルール

• このスキルが扱うすべてのドキュメントに unslop スキルを適用してください。このスキルが、AI らしい語彙、冗長な表現、曖昧な言い回し、書式上の不自然さなど、避けるべきパターンを管理します。
• PR の説明文やコミットメッセージも文章です。Diátaxis 以外のすべてのルールを適用してください。PR の本文は、レビュアーが 1 分以内に読める概要にします。swarm のログ、SHA の一覧、メトリクスの表を貼り付けず、リンクしてください。
• 製品の UI 文字列はドキュメントではありません。製品のコピーライティングガイドラインに従ってください。
• コードスニペットはタブでインデントしてください。実際のパスを記載してください。件数やツリー構造に関する記述は、コミット時点で正確な内容にし、再生成するコマンドも記載してください。

例

修正前：

proto インポートの上限スクリプトのパラメーターは budget.json で設定します。現在の件数を反映するためにコミット済みの上限を更新する --write を付けて実行する場合、上限を下げるときに限って実行することが重要です。上限を超えると CI は失敗します。

修正後：

budget.mjs は、コミット済みの上限を budget.json から読み込み、proto をインポートするファイルの数を数えます。件数が上限を超えると、CI は失敗します。上限を下げる場合に限り、budget.mjs --write を実行してください。