technical-writing

テクニカルライティング

太字またはバッククォートで示されたスキル名、あるいは /<name> として実行するスキルは、このスキルのディレクトリと同じ階層にある ../<name>/SKILL.md ファイルです。接頭辞なしで示された原則名は ../principle-<name>/SKILL.md です。ファイルを読み、その指示に従ってください。pstack のスキルのほとんどはユーザー専用なので、スキルツールでは読み込めません。

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

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

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

使う語はコードベースにあるものにしてください。同義語や説明ではなく、実際のシンボル名、ファイル名、フラグ名、コマンド名を書きます。

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

リズムに変化をつける

すべてのレイヤーに従っていても、文書が機械的に見えることがあります。すべての文が短く切られ、見解がなく、具体性にも欠けている状態です。

• 意図的に文の長さを変えてください。短い文は要点を印象づけます。長い文には、条件や結果を含む情報を盛り込みます。
• 1 文に 1 つの考えを入れることは、すべての文を同じ長さにすることではありません。2 つの考えを含む文は分けます。1 つの考えを述べる長い文は残します。
• 文書の種類が許す範囲で、見解を示してください。説明ではトレードオフを検討し、長所と短所を並べるだけでなく、それらをどう評価するかを述べます。リファレンスは事実に徹します。
• 無機質な表現より具体的な表現を選んでください。「スキーマの変更で問題が起きる可能性があります」ではなく、「列名を変更するとビルドが失敗します」と書きます。

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

1つのドキュメントにつき、モードは1つです。次の2つの質問で決めます。内容は行動（実行）と理解（思考）のどちらに役立つか、そして学習と作業のどちらに役立つか。

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

このコンパスは、ドキュメント全体にも、1つの文にも使えます。

チュートリアル：実践を通じた学習。 学習者の成功は、学習者ではなくあなたの責任です。学習者が「学ぶ」ことではなく、何を作るのかを最初に伝えます。各ステップで、早い段階から頻繁に、目に見える結果を生み出します。期待される出力、プロンプトの変化、ログの行など、何が表示されるかを伝えます。説明は1つの節とリンクに絞ります。具体的に書きます。「一緒に」という立場で、コマンド形式で書きます。「まず、xを実行します。次に、yを実行します。」

ハウツー：目標に向けた手順。 マシンが実行できる操作ではなく、人が抱えている問題を解決します。読者の能力を前提とし、教えることは省きます。行動だけに絞ります。余談、背景説明、それ自体を目的とする網羅性は含めません。代わりにリンクします。分岐や判断の余地を設けます。「xにしたい場合は、yを実行します。」ガイドの名前には作業内容を使います。「レーダーアレイを調整する方法」とし、「レーダーアレイの調整」とはしません。

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

解説：理解とその理由。 範囲を限定した1つのトピックを扱い、製品から離れて読んでも理解できるようにします。各タイトルの前に暗黙の「〜について」を付けても自然なものにします。実際の「なぜ」という問いを軸にします。設計上の判断、歴史、制約、代替案などの背景を示します。意見を述べてよいのはここだけです。

モードを混在させてはいけません。チュートリアルにリファレンスの表を入れたり、リファレンスにチュートリアルのような手取り足取りの説明を入れたり、ハウツーで議論したりしないでください。分割して、相互にリンクします。

読者に向けて文を書く（Google デベロッパー向けスタイル）

• 読者に「あなた」と呼びかけ、現在形で書きます。「will」は、本当に後で起きることに限って使います。
• 誰が何をするのかを明確にします。「チェックされます」ではなく「コンパイラがチェックします」と書きます。行為者が不明、または重要でない場合に限り、受動態を使えます。
• 指示は命令形で書きます。「送信」をクリックします。事実は明確に述べます。「実行されるべきです」とは書きません。
• 条件を指示の前に置きます。「ドキュメントを削除するには、［削除］をクリックします。」
• 一般的なケースを先に書きます。例外はその後に続けます。
• 詳しい友人のような口調にします。流行語や比喩表現は使わず、指示に「お願いします」を入れません。手順では「単に」「簡単に」「すばやく」は使いません。簡単なら、読者はここに来ていないはずです。
• 予告（「まもなくサポートする予定です」など）はせず、連続する文を同じ言い回しで始めないようにします。
• リンク先がわかる言葉でリンクします。ページタイトルや短い説明を使い、「ここをクリック」は使いません。ページ内で背景を説明してから、外部ページにリンクすることを優先します。
• 見出しは単なるトピック名ではなく、要点を示します（「モード」ではなく「まずモードを選ぶ」）。文頭のみ大文字にします。作業の見出しは動詞句のみ（「インスタンスを作成する」）、概念の見出しは名詞句にします。ページにつきh1は1つとし、見出しレベルを飛ばしません。
• 手順には番号付きリスト、それ以外には箇条書きを使います。リストの前には、完結した文を置きます。項目の形式をそろえます。
• コードはコードフォントで、UI要素は太字で表示します。列挙では最後の項目の前に「および」を置きます。「など」は使わず、リストが一部のみを示す場合は、最初にその旨を伝えます。

ステートメントを一度に一つずつ読み込む（STE ルール）

• 文ごとに指示は一つにします。それ以外の箇所でも、文ごとに考えは一つにします。
• 20語程度を超える指示文と、25語程度を超えるその他の文は分割します。
• 警告や条件は、それが適用される手順の前に置きます。「熱した油が皮膚に触れると、けがをするおそれがあります。」
• 「the」と「a」は残します。「Remove backup file」は二通りに読めます。「Remove the backup file」なら一通りに読めます。
• 各単語に意味と役割を一つずつ与え、その使い方を保ちます。「check」が「調べる」という意味なら、「拘束する」という意味には使わないでください。
• 動作ごとに単語を一つ選び、統一して使います。ある箇所では「start」、別の箇所では「initiate」とするのではなく、「start」に統一します。
• 手順は説明文ではなく、直接的な命令文で書きます。受動態も使いません。「the component must be installed」ではなく、「Install the component」と書きます。
• 可能な限り「-ing」形の語を避けます。

どの文も二通りに読めないようにする（グローバル英語）

• 「only」や「not」などの語は、意味を変える語の隣に置きます。「only fails on growth」と「fails only on growth」は意味が異なります。
• 長い名詞の連なりは分割します。「the proto import budget check script」は「the script that checks the proto-import budget」とします。
• 「it」「they」「this」が何を指すのか、明確にします。迷ったら名詞を繰り返します。節全体を指す「this」や「which」は使いません。
• 動詞を省略しません。「Phase 1 moves the converters and Phase 2 the runtime」では、Phase 2 の動詞がありません。動詞を補ってください。
• 構造を示す小さな語も省略しません。「Ensure that the switch is off」の「that」のような語を残します。語数を減らすために明確さを犠牲にしてはいけません。
• 並列項目の誤読を防げる場合は、冠詞を繰り返します。別々のものを指す場合は、「the client and host」ではなく「the client and the host」とします。
• 文の解釈によって「and」や「or」が異なるグループを作る場合は、どの部分を結び付けるのか明記します。「Both...and」「either...or」「if...then」を使えば、追加の説明なしで曖昧さを解消できます。
• セミコロンではなくピリオドを使います。ダッシュは新しい文に置き換えます。
• 括弧内のテキストは、文法的に完結したまとまりにするか、独立した文にします。複数形を「(s)」で表してはいけません。
• スラッシュは使いません。「a/b」や「and/or」ではなく、「a, b, or both」と書きます。
• 同じものは、どこでも同じ名前で呼びます。一つのものに対して、文書内で「the gate」「the ratchet」「the budget check」と呼び分けると、三つのものだと誤解されます。変更されていない名称は変えないでください。
• 慣用句、口語表現、ラテン語の略語、比喩は避けます。

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

• このスキルが対象とするすべての文書に、unslop スキルを適用します。AI 特有の語彙、冗長表現、曖昧な表現、書式上の癖など、避けるべきパターンはそのスキルに従います。
• PR の説明文やコミットメッセージも文章です。Diátaxis 以外のすべてのルールを適用します。PR の本文は、レビュアーが1分以内に読める概要にします。スウォームのログ、SHA の一覧、指標の表を貼り付けず、リンクを記載します。
• 製品の UI 文字列はドキュメントではありません。製品のコピーガイドラインに従います。
• コードスニペットはタブでインデントします。実際のパスを書きます。数やツリーに関する記述は、コミット時点で正確であることを確認し、再生成に使うコマンドも記載します。

例

変更前：

proto のインポートに関するラチェット予算スクリプトのパラメーターは、budget.json で設定します。なお、現在の数を反映するためにコミット済みの予算を更新する --write を指定して実行するのは、予算を引き下げるときだけにすることが重要です。予算を超えると、CI は失敗します。

変更後：

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