japanese-tech-writing

name	japanese-tech-writing
description	日本語の技術文書・書籍原稿の文章規範（整形、段落と論証の構成、論証の厳密さ、読み手の負荷、視点と語り、演出の抑制、LLM 口調の禁止、冗長の排除）。日本語で章・草稿・記事・解説文を書くとき、または推敲・リライトするときに使用する。
source	https://gist.github.com/k16shikano/fd287c3133457c4fd8f5601d34aa817d

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

日本語で技術的な文章（レポート、PR・イシュー本文、コメント、解説文）を書く・推敲するときは、以下の規範に従う。 書籍の章や記事などまとまった原稿では、references/manuscript.md の規範（整形の追加規範、段落と論証の構成、読み手の負荷、視点と語り、演出の抑制、見出し、読者への誠実さ）もあわせて読んでから書く。

整形

• 一文ごとに改行する。段落の区切りは空行で示す。
• コード、差分、ログ、設定ファイルの断片はコードブロックで示す。
• ダッシュ（em ダッシュ —、horizontal bar ―、いわゆる2倍ダッシュ「——」）を日本語の地の文・見出しで使わない。同格・補足の挿入（「A——挿入——B」）は括弧（）に、言い換え・敷衍（「A——B」）は句点で二文に分けるか読点でつなぐ。範囲を示す en ダッシュ – や英語の複合語（Curry–Howard など）、コードブロック・書誌情報は対象外。
• 中黒（・）を日本語の並列で使わない。ただし単一の固有名詞の内部では使ってよい。
• 用語とその定義を並べる箇条書きは、区切り線ではなく全角コロンで「用語：説明」と書く。

論証の厳密さ

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

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

LLM っぽい表現の禁止

LLM が大量生成する、中身のない型に誘惑されない。書き上げたら、この節で点検する。 本書の術語（本質的複雑さ、回収、判断の配置など）を議論に使うのはよい。空虚な装飾として使うのが問題である。

次のような言い回しは、論点を増やさず「ちゃんと書いている感」だけを付ける LLM 口調である。使わない。

• 予告と総括：「重要なのは〜である」「本章では〜を扱う／探求する」「ここでは〜について見ていく」「まとめると」「要するに」（直前の言い換えだけのとき）、「〜に他ならない」
• 正面から系：「正面から扱う」「正面から回収する」「正面から見る／書く／立てる」——中身の代わりに姿勢だけを宣言する
• 空虚な形容：「不可欠」「核心的」「鍵となる」「根本的な」（主張の中身を説明せず強調だけする）、「多角的」「包括的」「総合的」（何をどう見たかを書かない）
• 空虚な動詞：「掘り下げる」「深掘りする」「言語化する」（何をどう書いたかを示さず終わる）、「触れる」「言及する」（一段落で済ませるだけ）
• 接続の型：「〜において」「〜という側面から」「〜の観点から」（新情報なし）、「さらに」「また」「加えて」の連打
• 弱い緩和と称賛：「〜と言えるだろう」「〜かもしれない」（根拠なく主張を弱める場合だけ。推量・仮定・読者の疑念・作中人物の認識なら残す）、「非常に」「極めて」「大いに」（中身のない強調）

悪い例：「本章では、〇〇の理論を正面から扱う」「この前提を、ここで正面から回収する」「多角的に分析すると、重要なのは〜である」。 良い例：「本章では、〇〇の理論を扱う」「ここで、この前提を回収する」「評価の核心は、正しさを誰が知っているかにある」。

冗長の排除

無駄な文章をなるべく残さない。

• 同じ主張を言い換えて繰り返さない。一つの主張は一度だけ書く。
• 隣接する節が同じことを別の角度で述べているなら、役割が重複している。片方に吸収して一つの節にまとめる。
• 場面を描写した直後に、その内容を要約し直さない。意味づけの一文（「このような作業は、ほぼ完全に任せられる」など）だけを置く。
• 同じ論理的役割を持つ並列の事実は、文を分けて重ねず一文にまとめる。その事実群の論理的地位は文頭の語で示す（「当然、経理部の月次処理も顧客の支払いも〜」）。
• 読者が自力で補える中間段階の説明は書かない。
• 数文にわたる議論を一文に圧縮できるなら、圧縮した一文だけを残す。要約の合図として「要するに」を使ってよい。
• 接続や評価のためだけの文（「それ自体はよいことである」など）を置かない。
• 想像上の読者との問答（問いを立てて一語で答える形など）を修辞として使わない。主張はそのまま述べる。読者の反応を演じて応答する形（「〜と感じたかもしれない。そのとおりである」）も同様に避け、譲歩は地の文で簡潔に行う（「もちろん、処置そのものは開発者が決める問題ではない」）。
• 読者が抱きそうな発想を、メタな枠取り（「ここまでの話には自然な続きがある」「〜という発想である」）で紹介しない。その発想自体を直接書く。読者の疑問なら疑問文のまま書いてよい（「その保守も任せればよいのではないだろうか」）。
• 「本書もそれを否定しない」のような、著者の立場の弁明や断りを書かない。事実の記述（「〜に書かせる場合が多い」）だけを置く。
• 文脈を最短で読み手と共有できる文章にする。導出を一歩ずつ展開しなくても伝わるなら、構造に名前を与えて言い切る。
• 本文でまだ導入していない概念や文書名を、先回りして持ち出さない。
• ためらいのある弱い述語（「有効な対策であり」など）で済ませない。本文内の根拠で確定していることは強く具体的に言い切る（「活用において必須であり」など）。ただし、不確実性・可能性・仮定・読者の疑念を表すための弱い述語は保持する。語調を整えるための意図的な緩和（「必須だと言ってもいい」など）は許す。
• 文章のリズムを作るための接続表現（「しかし一方で」など）は、冗長と見なさない。