japanese-tech-writing

name	japanese-tech-writing
description	日本語の技術文書における論証、演出の抑制、整形の規範。段落単位の再配置・削除・橋渡しで論証の筋を通す編集も扱う。技術ブログ記事、design doc、ポストモーテムを書くとき、推敲するとき、または議論の筋を点検して直すときに使用する。

日本語で技術文書を書く場合は、以下の規範に従う。規範同士が衝突する、または適用範囲の判定に迷うときは、確認済みの事実への忠実さ（未確認なら不確実性を保ち、創作しない）と論証の筋を優先し、演出・予告・強調の側には倒さない。

論証

段落と論証の構成

パラグラフライティングを基本とする。段落は論証の一歩であり、読者は段落単位で論理を追えなければならない。

• 一つの段落には一つのトピックだけを置く。場面の進行（調査、報告、検証、評価）が複数混ざった長い段落は、一歩ずつの段落に分割する。
• 同一対象の論述が別の話題によって中断され、後で戻ってくる構成を避ける。段落内・段落間の双方で点検する。
• 段落の最初の文を読めば、その段落が何の話かわかるようにする。
• 前の段落から話が続く場合は、段落先頭に論理関係を接続表現で明示する（「であれば」「実際」「しかし」「この例自体からも」）。新しい話題を持ち込まず、前段落で導入した語・問い・未解決事項を受ける。
• 結論は、反論と疑念の処理を終えてから一度だけ置く。結論を出してから反論を処理し、結論を言い直す構成にしない。
• 読者が立てそうな誤った解釈は、明示的に否定してから本当の理由を述べる（「その理由は『〜だから』ではない。〜だからだ」）。
• 「AではなくB」と否定するときは、否定の根拠を一文添える。反実仮想（「もしAなら、〜だっただろう」）が使えることが多い。
• 何かを否定・限定するときは、否定する命題そのものを「」で正確に書き出す（「明文化されていればすべてを任せられる」を意味しない、など）。「何もかもが解決するわけではない」のような漠然とした否定で済ませない。
• 譲歩（「確かに〜」）では、事実の確認にとどめる。あとで訂正する内容を著者の声で因果として断定すると、自己矛盾になる。表面的な診断を一度認めたいときは、読者や通説の声に帰属させる（「〜と要約できてしまうかもしれない」）。
• 山場に置きたい情報（数値、固有の事実）は、その手前の段落で先出ししない。
• 論証や場面の途中に挟むと流れを切る要素は、論証が一段落した位置に置く。例への弁明（作為的に見える、への先回りなど）は次の節の冒頭でまとめて処理し、「後で扱う」「別の記事で扱う」のような前方参照は段落末やセクション末に置く。

論証の厳密さ

文章の論理にツッコミどころを残さない。書き上げたら、読み手の反論を先回りして次の点を点検する。

• 「かもしれない」「だろう」「ようだ」「らしい」を削って断定に直せるのは、本文内の根拠によって命題が確定している場合に限る。事実未確認の可能性、作中人物の認識、ログからの推定、読者が抱きそうな疑念、反実仮想を表す場合は、その不確実性を保つ。
  • 悪い例：「提示し続けているかもしれない」を「提示し続けている」に変える。
  • 良い例：「提示し続けている可能性がある」のように、不確実性を残して文を整える。
• 区別すべき対象（別々の決定、別々の原因、種類の違う問題）を「同じ」と一括りの言葉でくくらない。
  • 悪い例：相互依存する三つの未決事項を「同じ決定を別々に下していた」と書く。
  • 良い例：「どれも別々の決定であり、しかも互いに依存している」と腑分けする。
• 複数の要因がある事象を、単一の原因に還元しない。例が複数種類の問題を含むなら、それぞれを切り分け、どの道具がどれを説明するのかを対応づける。悪い例：契約の不在と情報隠蔽の失敗が混ざった事故を、丸ごと「情報隠蔽の問題」と説明する。事実が単一の直接原因を確定しているなら、それを名指すのは還元ではない。
• 因果を主張するときは、その機構（なぜそうなるのか）を一文で示す。「AだとBになる」とだけ書いて理由を省略しない。悪い例：「手順で分けると変更が全体に波及する」。良い例：「各工程がデータを受け渡すための表現を共有してしまい、その表現を変えると全体に波及する」。
• 因果の機構を、比喩的な動詞（「すり抜ける」「潜り抜ける」「抜け落ちる」「素通りする」「かいくぐる」など）で代替しない。動詞が動きを描写しているように見えても、なぜそう動くのかの理由が明示されていなければ機構の説明にはならない。
  • 悪い例：「モダン構文が Next.js のトランスパイル網をすり抜けてバンドルに混入する」（なぜ「すり抜ける」のかが不在）
  • 良い例：「Next.js はデフォルトで node_modules 内のコードをトランスパイル対象外にするため、依存パッケージがトランスパイル前の構文のままバンドルに含まれる」（対象外にする、という技術的事実が機構の実体）。
• 機構が本文の根拠や確認済みの事実から確定していない場合は、創作して補わない。相関の記述に留めるか、不確実性を保った推定として書く。
• 検出・保証・解決を「必ず」できるかのように書かない。条件付きで正確に述べる（「〜しやすい」「〜できることが多い」「〜が成り立つときに限り」）。
• 主張は、挙げた例が実際にその全体を支えているかを確認する。例が主張の一部しか支えないなら、主張の範囲を例に合わせて狭める。
• 前方に逃がした論点（「後で扱う」等）は、本当にそこで回収されることを確認する。
• 譲歩や限定（「ただし」「とはいえ」）を置いたら、その後で必ず論を進める。逆接で終えて宙吊りにしない。
• 節末で未解決の論点を次の節や本論へ渡すときは、予告文（「本章では〜を扱う」）ではなく、それを事実として名指す文で閉じる（「〜をどう設計するかにかかっている」など）。
• 本文でまだ導入・定義していない語（術語、概念、文書名など）を、先回りして使わない。中心となる語は、それを使う前に定義・対象範囲を述べる。
• 複数の概念を一つの上位語にまとめるときは、命名の直前に、それらが同じものに帰着すると一文で述べる（「これらはいずれも〜に帰着する。以後まとめて〇〇と呼ぶ」など）。
• 本文の中心語を、似た別語にすり替えて接続を作ったように見せない。例：「見抜く」を「見分ける」に逃がすなど。
• 例や研究が主張とは別の問いに答えていないか確認する。例の範囲のズレではなく、答えている問いの方向のズレを見る。
• 引用・定式化・数学用語を出しても、それが次の判断や主張を変えないなら削る。装飾的な引用を残さない。
• 例が作為的に見えうる場合は、読者の疑念を先回りして認め、現実に十分あり得ることの根拠を短く添える。その根拠は、著者の断定（「十分あり得る状況だ」）ではなく、読者自身の経験に訴える一般的事実や通説に求める（「この症状は珍しくないだろう」「〜という言い方もよく耳にする」）。
• 確認していないことを、確認したかのように滑らかに書かない（ログを見ていないのに「ログを確認すると〜だった」と書く、など）。

論証の点検と編集

書き上げた原稿の論証の筋を点検し、段落単位で修正する手続き。

1. 対象範囲を段落単位に分ける。
2. 各段落について、次の三つを一文で書き出す。

• 前段落から何を受けているか
• その段落が本文で果たす役割
• 次段落へ何を渡しているか

3. この三つのどれかが書けない段落を、ギャップ候補にする。ただし冒頭段落の「受けるもの」と末尾段落の「渡すもの」は空でよい。空欄が構造上正常か中断由来かは、隣接段落との論理の連続で判定する。
4. ギャップ候補について、「論証の厳密さ」の検出項目（言い換えによる逃げ、証拠の型違い、理論の見せびらかしなど）のどれに当たるかを判定する。一つの候補が複数の項目に該当することがあるので、すべて挙げ、それぞれへの修正を検討する。
5. 修正は、段落の中身だけでなく、順序・削除・橋渡しを含めて考える。論述対象が異なるが論理的関連は残る段落は、削除ではなく別の節への移設を第一候補にし、移設先での橋渡しの要否まで判定する。書き換えは元文の情報の範囲内で行い、機構の明示まで踏み込んでよいが、範囲外の事実は創作しない。修正後、段落ごとに「受けるもの」「果たす役割」「渡すもの」を再確認する。

演出の抑制

視点と語り

• 例示では、結果の羅列や受動態（「特定され、判明した」）ではなく、行為者を主語にした動作の連なり（「リポジトリを調査して特定し、見つけてくれた」）で書く。
• 「入社2年目のエンジニアが」のような架空の人物設定を無意味に冠しない。
• 論証の中で読者を「あなた」と呼ばず、役割名（「開発者」「読者」）で書く。二人称の呼びかけは、場面への導入（「〜としよう」）や記事の結びなど、限られた要所にとどめる。
• 対象を指す語は具体的に選び、途中で曖昧語（「AI」「ツール」「文脈」等）に後退しない。ただし定式化する前の導入語として「文脈」などを使うのはよい。
• 術語・訳語は、その分野で慣用されている語を選ぶ（first-class citizen は「一等市民」ではなく「第一級オブジェクト」など）。意味の近い漢語を一般語の感覚で充てない。
• 人物そのものに言及するときは原綴りで書く（Lehman、Bainbridge）。ただし、歴史上の人物や、人名を冠した概念を定着名で紹介するときは、日本語で通用しているカタカナの通称を使う。
• 術語の響きを持つ語を、術語でない場面に流用しない（システムから人間までの連なりを「経路」と呼ぶ、など）。「届くまでの流れ」「あいだに何があるか」のように普通の言い方で書く。
• 法律・行政・出版など他分野の硬い語（「正本」「憲法」「布告」など）を、技術文書の比喩や格付けとして使わない。「唯一の参照元」「最優先のルール」のように、指す内容をそのまま書く。

演出と修辞

修辞は全面禁止ではなく、効果を生む箇所でのみ使う。

• 溜め（「ここには〜が潜んでいる」）や修辞疑問で導出を演出するのは、緊張が議論に効く要所に限る。説明で足りる箇所では、そのまま述べる。
• 短い決め台詞を独立した段落にして緊張を作る演出を多用しない。
• 段落内の短い体言止め（「ここまでわずか数十秒。」など）は、場面の山場に限り使ってよい。
• 本文中の太字強調を多用しない。誤読を防ぐ否定や節の帰結など、論理の要所に限り、一節に一、二箇所まで使ってよい（導入部でも可）。それ以外は文の順序と構造で際立たせる。
• 「〜してはならない」という命令調の断定より、「〜するわけにはいかない」のような、作業者の判断として書く形を選ぶ。
• 転回点を過剰に劇的にしない。事実を述べる一文で足りる場合が多い。議論の山場にかぎり、感嘆符つきの短い一文程度は許容する。
• 帰結の列挙（「データは失われ、信頼は損なわれ、復旧には数日を要する」のような畳みかけ）によって事故や危険を煽らない。
• 「AではなくBだった」という対句の決め台詞を多用しない。軽い補足や評価は括弧書きで添えてよい。
• 慣用表現をひねった言い回し（「知識を体に入れる」など）や、指す内容が一意に決まらない比喩（「報告の外側に世界が広がっている」など）を使わない。平易な動詞でそのまま言う（「身につく」「気付く機会が減る」）。

空句と冗長

LLM が大量生成する空虚な表現と、冗長な文章構造を排除する。書き上げたら、この節で点検する。点検対象の文書が主題とする分野の術語を議論に使うのはよい。空虚な装飾として使うのが問題である。

予告と総括

• 「重要なのは〜である」のような前置きで主張を予告しない。主張をそのまま書く。ただし、主張の様式を宣言する前置き（「標語として言い換えれば」など）は使ってよい。
• 「本章では〜を扱う／探求する」「ここでは〜について見ていく」のような予告を書かない。
• 「まとめると」「要するに」を、直前の内容の言い換えだけに使わない。数文にわたる議論を一文に圧縮できるなら圧縮した一文だけを残し、その合図として使うのはよい。
• 中身を説明せず断定を強めるだけの「〜に他ならない」を使わない。
• 場面を描写した直後に、その内容を要約し直さない。意味づけの一文だけを置く。

空句と装飾

• 「正面から扱う」「正面から見る」のような、中身の代わりに姿勢だけを宣言する表現を使わない。
• 「不可欠」「核心的」「鍵となる」「根本的な」「非常に」「極めて」「大いに」のような、主張の中身を説明せず強調だけする語を使わない。
• 「多角的」「包括的」「総合的」のような、何をどう見たかを書かない形容を使わない。
• 「掘り下げる」「深掘りする」「言語化する」のような、何をどう書いたかを示さず終わる動詞を使わない。
• 「触れる」「言及する」を、一段落で済ませるだけの用途で使わない。

反復と要約

• 同じ主張を言い換えて繰り返さない。一つの主張は一度だけ書く。
• 隣接する節が同じことを別の角度で述べているなら、役割が重複している。片方に吸収して一つの節にまとめる。
• 同じ論理的役割を持つ並列の事実は、文を分けて重ねず一文にまとめる。その事実群の論理的地位は文頭の語（「当然」「実際」「例えば」など）で示す。
• 読者が自力で補える中間段階の説明は書かない。
• 接続や評価のためだけの文（「それ自体はよいことである」など）を置かない。

メタ発言と読者演出

• 想像上の読者との問答（問いを立てて一語で答える形など）を修辞として使わない。主張はそのまま述べる。読者の反応を演じて応答する形（「〜と感じたかもしれない。そのとおりである」）も同様に避け、譲歩は地の文で簡潔に行う。
• 読者が抱きそうな発想を、メタな枠取り（「ここまでの話には自然な続きがある」「〜という発想である」）で紹介しない。その発想自体を直接書く。読者の疑問なら疑問文のまま書いてよい。
• 「本記事もそれを否定しない」のような、著者の立場の弁明や断りを書かない。事実の記述だけを置く。

弱い述語と接続の型

• ためらいのある弱い述語（「有効な対策であり」など）で済ませない。本文内の根拠で確定していることは強く具体的に言い切る（「活用において必須であり」など）。弱い述語を残す・削るの判定は「論証の厳密さ」冒頭の項に従う。語調を整えるための意図的な緩和（「必須だと言ってもいい」など）は許す。
• 「〜において」「〜という側面から」「〜の観点から」のような、新情報を加えない接続表現を使わない。
• 「さらに」「また」「加えて」の連打を避ける。
• 削ると文間の論理関係（逆接、対比）が読み取れなくなる接続表現（「しかし一方で」など）は、冗長と見なさない。

整形

整形規則

• コード、差分、ログ、設定ファイルの断片はコードブロックで示す。
• 用語の由来や定式化の名称など、本筋から一段外れる補足は、本文に並べず脚注（[^ラベル]）に降ろす。
• 定義や分類の列挙は箇条書きで示してよい。
• 用語を初めて定義・導入するときは、本文中でも箇条書きでも、その語を太字にする。すでに導入した語を話題として指すとき、引用、通称には「」を使い、太字と使い分ける（初出の定義は太字、以後の言及は「」）。
• 節や下位トピックの区切りには見出し記法（## など）を使う。太字だけの一行を見出しの代わりに置かない。
• ダッシュ（em ダッシュ —、horizontal bar ―、いわゆる2倍ダッシュ「——」）を日本語の地の文・見出しで使わない。同格・補足の挿入（「A——挿入——B」）は括弧（）に、言い換え・敷衍（「A——B」）は句点で二文に分けるか読点でつなぐ。範囲を示す en ダッシュ – や英語の複合語（Curry–Howard など）、コードブロック・書誌情報は対象外。
• 中黒（・）を日本語の並列で使わない。ただし単一の固有名詞の内部では使ってよい。
• 見出しに、区切り線（罫線 ─ U+2500 やダッシュ類）で「種別──主題」「主題──概念」のように二要素を詰め込まない。見出しは単一の自然な句にする（要素を一つに絞るか、助詞・読点でつなぐ）。
• 用語とその定義を並べる箇条書きは、区切り線ではなく全角コロンで「用語：説明」と書く。

見出しの付け方

見出しは、その節が答える問い、または扱う対象を指す句にする。疑問形か断定形か名詞句かといった形式は問わず、本文のトーンに合うほうを選ぶ。

• 作業の手順だけを述べる見出し（「例に戻す」「〜を読み直す」など）や、情報量のない見出し（「まとめ」「その他」など）にしない。
• 見出しを、節の結論を言い切って読者に先にオチを知らせる「セリフ」にしない。節が扱う対象を名指すのは可で、結論の中身（答え、数値、固有の事実）まで言い切るのが不可である。