technical-writing

テクニカルライティング

目指すのは、疲れたエンジニアが一度読んだだけで理解できる文章です。そのために、4つの層を意識します。それぞれ問いは1つです。この文書はどの種類か。文はどのように読者に語りかけるか。各文にどれだけの情報を盛り込むか。どの文にも複数の解釈の余地がないか。4つすべてを適用します。

この層の上には、3つのルールがあります。

• 役に立たない言葉はすべて削ります。 ある言葉をなくしても文が成り立つなら、その言葉は不要です。「するために」は「するため」に。「注意することが重要です」は何も伝えていません。
• 短く、日常的な言葉を使います。 「活用する」ではなく「使う」。「促進する」ではなく「助ける」。「実行する」ではなく「する」。長い言葉を使うなら、その長さに見合う正確さが必要です。
• ルールのせいで文が悪くなるなら、別の方法で文を直すか、そのままにします。 ルールは読者のためにあります。すべてのルールに従っていても機械が書いたように聞こえる文は、失敗です。

使う言葉はコードベースに合わせます。同義語や説明ではなく、実際のシンボル名、ファイル名、フラグ名、コマンド名を使います。

専門用語を作り出さないでください。開発者が口にする言葉を使います。「移動する」「削除する」「減る一方の予算」であって、「退避する」「ラチェット」「エンドゲーム」ではありません。文書内で初めて使うときに意味を説明するなら、名前の付いたパターンを使ってもかまいません。新たに不適切な表現とその置き換えを提案する場合は、unslop の抽象的な比喩に関するルールへの追加案として、差分を添えて返信してください。そのスキル自体は編集しないでください。

リズムに変化をつける

各層によって、文書で何を伝え、各文にどれだけの情報を盛り込むかが決まります。すべての層に従っていても、機械が書いたように読めることがあります。どの文も短く切り詰められ、視点がなく、具体性もありません。

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

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

1つのドキュメントに1つのモードを使います。2つの問いで選べます。内容は行動（実行）と理解（思考）のどちらを促すか、また学習と作業のどちらに役立つかです。

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

この指針は、ドキュメント全体にも1文にも適用できます。

チュートリアル：実践を通じた学習。 あなたは教師です。学習者の成功は、学習者ではなくあなたの責任です。冒頭では、学習者が「学ぶ」ことではなく、何を作るのかを伝えます。各ステップでは、早い段階から頻繁に目に見える成果を出します。期待される出力、プロンプトの変化、ログの1行など、何が表示されるべきかを伝えます。説明は1つの節とリンクに絞ります。教えるための中断は、レッスンの流れを妨げます。具体的に書きます。「まず、xを実行します。次に、yを実行します」のように、「私たち」を主語にして命令形で書きます。

ハウツー：目標を達成するための手順。 機械が実行できる操作ではなく、読者が抱えている問題を解決します。読者には十分な知識があることを前提にします。教える内容は省きます。行動だけを記し、脱線、背景説明、網羅性のためだけの内容は入れません。必要な内容にはリンクします。分岐や判断の余地を設けます。「xをしたい場合は、yを実行します」のように書きます。ガイドには作業内容を名前として付けます。「レーダーアレイを較正する方法」とし、「レーダーアレイの較正」とはしません。

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

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

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

出典：diataxis.fr、2026-07-18取得。

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

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

出典：developers.google.com/style、2026-07-18取得。

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

• 1文につき指示は1つにします。それ以外の箇所でも、1文につき考えは1つにします。
• 20語程度を超える長い指示文や、25語程度を超えるその他の文は分割します。
• 警告や条件は、それが適用される手順の前に置きます。「熱い油が肌に触れると、けがをすることがあります。」
• 「the」や「a」を残します。「Remove backup file」は2通りに読めます。「Remove the backup file」は1通りに読めます。
• 各単語には意味と役割を1つずつ持たせ、一貫して使います。「check」を「調べる」という意味で使うなら、「制止する」という意味では使いません。
• 動作ごとに単語を1つ選び、一貫して使います。ある箇所では「start」、別の箇所では「initiate」と書くのではなく、「start」に統一します。
• 手順は、説明文ではなく直接的な命令で書き、受動態は使いません。「the component must be installed」ではなく、「Install the component」とします。
• できる限り「-ing」形の単語を避けます。文法上の役割が多すぎるため、誤読を招きやすくなります。

出典：asd-ste100.org（Issue 9、2025年）、2026-07-18取得。番号付きのルールと辞書は仕様 PDF に記載されています。上記の原則は、応用可能な要点です。

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

• 「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」が何を指すか、1つに明確に定まるようにします。迷ったら名詞を繰り返します。節全体を指すために「this」や「which」を使ってはいけません。
• 動詞を省略しません。「Phase 1 moves the converters and Phase 2 the runtime」では、Phase 2 の動詞がありません。動詞を補います。
• 文の構造を示す短い単語は残します。「Ensure that the switch is off」では、「that」があることで文の構造が1通りに定まります。語数を減らすために明確さを損なってはいけません。
• 誤読を防げる場合は、列挙の各項目に冠詞を繰り返します。2つのものを指す場合は、「the client and host」ではなく「the client and the host」とします。
• 文が2通りに分けて読める場合は、「and」や「or」がどの部分を結び付けるかを明示します。「Both...and」、「either...or」、「if...then」を使うと、追加の語数なしで曖昧さを解消できます。
• セミコロンではなくピリオドを使います。ダッシュは新しい文に置き換えます。
• 括弧内の文は、文法的に完結させるか、独立した文にします。複数形を表すために「(s)」を使ってはいけません。
• スラッシュは使いません。「a/b」や「and/or」ではなく、「a, b, or both」と書きます。
• どのものも、常に同じ名前で呼びます。1つのものを指すのに「the gate」、「the ratchet」、「the budget check」を使う文書は、3つのものを説明しているように受け取られます。変更のない文を編集のたびに言い換えても、同じコストがかかります。変更していない部分は何度も書き換えないでください。
• 慣用句、口語表現、ラテン語の略語、比喩表現は避けます。英語を母語としない読者、翻訳者、エージェントには、平易な表現が最も理解されやすいです。

出典：Kohl 著『The Global English Style Guide』（SAS Press）。ガイドライン本文は Internet Archive および SAS のサンプル章から2026-07-18に取得しました。

文体とリポジトリ固有の事項

• このスキルが扱うすべてのドキュメントに unslop スキルを適用します。スロップのパターン一覧（AI の語彙、フィラー、曖昧な表現、書式上の特徴）は、このスキルで管理します。
• PR の説明とコミットメッセージも文章です。Diátaxis を除くすべてのレイヤーで、それらにもこの方針を適用します。レビュー担当者が1分以内に読める概要として、PR の本文を書きます。swarm のログ、SHA の一覧、メトリクスの表は貼り付けず、リンクを付けます。
• プロダクトの UI 文字列はドキュメントではありません。プロダクトのコピーガイドラインに従ってください。
• コードスニペットはタブでインデントします。実在するパスとシンボルを記述します。個数やツリーに関する記述は、コミット時点で正確な内容にします。再生成するコマンドも記載します。

実例

変更前：

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

変更後：

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