tech-writing

日本語技術文書の文章規範

日本語で技術的な原稿（書籍の章、記事、解説文）を書く・推敲するときは、以下の規範に従う。

整形

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

段落と論証の構成

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

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

論証の厳密さ

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

• 推量・可能性・読者の疑念・反実仮想として書かれている文を、機械的に断定へ変えない。 「かもしれない」「だろう」「ようだ」「らしい」は、根拠なく主張を弱めている場合だけ削る。 事実未確認の可能性、作中人物の認識、ログからの推定、読者が抱きそうな疑念、反実仮想を表す場合は、その不確実性を保つ。 断定に直せるのは、本文内の根拠によって命題が確定している場合に限る。 悪い例：「提示し続けているかもしれない」を「提示し続けている」に変える。 良い例：「提示し続けている可能性がある」のように、不確実性を残して文を整える。
• 異なるものを「同じ」とまとめない。区別すべき対象（別々の決定、別々の原因、種類の違う問題）を一括りの言葉でくくらない。悪い例：相互依存する三つの未決事項を「同じ決定を別々に下していた」と書く。良い例：「どれも別々の決定であり、しかも互いに依存している」と腑分けする。
• 複数の要因がある事象を、単一の原因に還元しない。例が複数種類の問題を含むなら、それぞれを切り分け、どの道具がどれを説明するのかを対応づける。悪い例：契約の不在と情報隠蔽の失敗が混ざった事故を、丸ごと「情報隠蔽の問題」と説明する。
• 章・節をまたいで、同じ概念の扱いを一致させる。ある節で「人間が決める」と分類したものを、別の節で「チームで合意する」と書かない。分類・定義・用語の地位は全体で揃える。
• 因果を主張するときは、その機構（なぜそうなるのか）を一文で示す。「AだとBになる」とだけ書いて理由を省略しない。悪い例：「手順で分けると変更が全体に波及する」。良い例：「各工程がデータを受け渡すための表現を共有してしまい、その表現を変えると全体に波及する」。
• 検出・保証・解決を「必ず」できるかのように書かない。条件付きで正確に述べる（「〜しやすい」「〜できることが多い」「〜が成り立つときに限り」）。
• 主張は、挙げた例が実際にその全体を支えているかを確認する。例が主張の一部しか支えないなら、主張の範囲を例に合わせて狭める。
• 「次節で扱う」と前方に逃がした論点は、本当にそこで回収されることを確認する。回収しない伏線を張らない。
• 譲歩や限定（「ただし」「とはいえ」）を置いたら、その後で必ず論を進める。逆接で終えて宙吊りにしない。
• 節の中心となる語は、その節以前に定義・対象範囲を述べてから使う。定義せず使い始めない。
• 複数の概念を一つの上位語にまとめるときは、命名の直前に、それらが同じものに帰着すると 一文で述べる。腑分けの逆の操作にも橋を架ける。