technical-writing

社内向け技術文書の執筆

概要

執筆対象が社内向けの技術提案書、レビュー文書、アーキテクチャ説明、共有資料であり、背景、仮説、根拠、抽象化、実装への影響範囲を明確に説明することが重要な場合に、このスキルを使います。

こうした文書は技術報告に近く、宣伝文でも散文でもありません。落ち着いた語調を保ち、判断に至る経緯を示し、問題に沿って読み進められる段落にします。

使用する場面

• 社内向けの技術提案書、設計説明、レビュー文書、共有資料を書くとき
• 内容はあるものの、文体が大げさで、結論を急ぎ、根拠が足りない技術記事を修正するとき
• コード、モジュールの境界、アーキテクチャの変遷、可観測性、評価方法を説明するとき
• チャットの記録や議論の結論を、共有できる技術文書にまとめるとき

使用しない場面

• UI 文言、ボタンの文言、製品のマーケティング資料
• 外部ユーザー向けのヘルプドキュメント
• 純粋な API リファレンスや定型的なマニュアル

基本姿勢

まず読者の視点に立ち、そのうえで説明を進めます。

よくある書き方は、作者が読者より先に判断を下すものです。たとえば、明らかに、示しています、当然、本当のといった表現です。ここでは、次の三つの段階に分けるとよいでしょう。

1. 何を観察したか
2. その観察から何を導けるか
3. その導出を、現時点でどのような実装や組織のあり方に当てはめるのが適切か

より強い判断を示す場合は、少なくとも次のいずれかを満たす必要があります。

• 前の段落で対応する仮説を提示しており、この段落でその仮説に応答している
• 同じ段落の文脈に、相互検証された根拠がある
• 具体的なモジュール、コード、issue、trace、指標、実験結果を引用している

こうした悪い例には、共通する特徴があります。

• 論証を進めるのではなく、文章の進行を司る役割を担っている
• 条件、対象、制約、判断ではなく、作者の感想を表現している
• 英語の抽象的な文章表現を、そのまま日本語に持ち込んでいる
• 削除しても事実や論証、構成に影響しない

こうした文に出会ったときは、「もっと上品な表現に置き換える」のではなく、まず次のように対応します。

1. この文が本当に情報を提供しているか判断する
2. 情報を提供していないなら、そのまま削除する
3. 情報を提供しているなら、その情報を条件、対象、関係、結果として書き直す

推奨する構成

長文を書くときは、次の流れを優先します。

背景 -> 現状の分解 -> 仮説の提示 -> 節ごとの説明 -> 前の議論への立ち返り -> 影響範囲 -> 可観測性 / eval -> まとめ

一つのシステムを中心に記事を構成する場合は、各節を「前に提示したどの問題への回答か」が分かるように書きます。そうすれば、読者は現在の段落が何を解決しているかを把握でき、意見がただ並んでいるようには見えません。

もう少し具体的に言うと、よくある構成は次のとおりです。

• まず背景と目標を説明する
• 現状を分解する。特に既存システムの長所、限界、全体的な傾向を整理する
• 仮説や設計上の問題を提示する
• 各節で、各層の機能がどのように不足を補うかを説明する
• コード、モジュール、データフロー、観測の範囲、評価の範囲に立ち返る

ある節で表向きはモジュールを説明しているものの、実際には別の概念の位置づけを示すことが目的なら、次の構成を優先するとよいでしょう。

1. まず、短い quote で文脈をまとめる
2. quote には mindmap またはごく簡潔な構成図を優先して載せる
3. 次に、ライフサイクル図またはシーケンス図を示す
4. 最後に本文に入り、この概念をなぜここに置くのか、既存モジュールとどう対応づけるのかを説明する

冒頭に TL;DR を置いて、リーダーやレビュー担当者に読んでもらう場合は、次の三段構成を優先します。

1. まず、着想のきっかけや背景の変化を説明する
2. 次に、現在のシステムがすでに持つ入力と、まだ不足している構造を説明する
3. 最後に、新しいモジュールの設計とアーキテクチャ上の判断を説明する

この TL;DR に含める情報は、次の三種類に限ります。

• 理由
• 仮説
• 判断

TL;DR で記事全体の目次を繰り返したり、これから作者がどのように書くかを説明したりしないでください。

言語ルール

中国語の文体は、自然で平易な、技術者同士の説明を基本とします。

• 中国語の引用符は 「」 に統一する
• 修辞や比喩は控える。特に現場の開発者や社内レビュー向けの文書では控える
• 上から目線の口調を抑え、説教調を避ける
• 論説文のような対立的な文を避け、読者の理解の流れに沿って説明する
• 専門用語は正式名称で表記し、大文字・小文字を統一する。たとえば、プロジェクト内の Collector、Scheduler、Alert などの固有名は、文書全体で表記を一つに統一する
• 指標、機能、経路などの名詞を先に定めてから、動詞や形容詞を組み合わせる。流通性、絞り込み、集約、ヒット など、すでに確立した用語体系を優先して再利用し、その場で類義語を組み合わせない
• ここまで話したところで、引き続き見ていきましょう、この方向はさらに推し進める価値があります、まずこの件を取り上げて説明しましょう、最後に一言でまとめるとのような口語的なつなぎの表現は避ける。文章を進行させるだけで情報を含まない文は、そのまま削除する
• 現実的、重い、軽い、スムーズなどの曖昧な評価語は控え、具体的な制約、リスク、影響に置き換える

次のような文型は、少し抑えた表現にするよう意識してください。

• ……ではなく……
• ……ではなく、……にある
• なぜでしょうか。理由はとても単純です
• この経路はすでに明らかです
• 一つのことを示しています
• 自然に……する
• 本当の

より落ち着いた書き方は、一般に次のようなものです。

• まず……と考えるかもしれません
• 今日のコードに目を戻すと、比較的安定した傾向がいくつか見えてきます
• これらのモジュールをたどっていくと、……と整理できます
• 前に述べた仮説に対する、より具体的な答えがここから見えてきます
• まず判断を控えめにし、後でコードや指標を踏まえて説明します

段落の中心となる問いを強調する場合は、**...** を適度に使えます。ただし、本当に重要な問いだけに使い、通常の判断文まで何でも太字にしないでください。

バズワードの使用禁止リスト

以下の言葉は、中国語の技術文書では「情報があるように見えて、読んでも何が起きたのか分からない」表現になりがちです。見つけたら立ち止まり、具体的な行動、対象、制約に置き換えられるなら置き換えてください。

原則として、一語ずつ置き換えるのではなく、一文ごとに書き直します。元の文で情報を担っているのが専門用語だけなら、その文には情報がないことがほとんどです。削除して論証に抜けが生じるか確かめ、抜けるなら具体的な内容を補い、抜けないなら削除します。

抽象語が主役になる表現

• エコシステム／エコシステム内の位置づけ／製品エコシステム → 具体的な依存関係、ユーザーの種類、連携先を列挙する
• 力を与える／ユーザーに力を与える → ユーザーが X できるようにする／X の機能を Y に提供する
• クローズドループ／クローズドループを形成する → X の後に Y もつながるようになった／現在は A から B に進み、再び A に戻れる
• 取っ掛かり／中核となる取っ掛かり → 変更できる変数は X
• マインドシェア／ユーザーのマインドシェア／メンタルモデル → ユーザーは X を初めて見たときにどう考え、どう操作するか
• 経路を接続する／接続する → A から B を呼び出せるようになった／A に書き込まれたデータを B からも読み取れる
• 蓄積する／経験を蓄積する／方法論を蓄積する → docs/X に記録する／skill / runbook にまとめる
• 実現する／機能を実現する／利用場面に落とし込む → A モジュールで実装する／B の業務で使う
• 心的負担／認知負荷 → X 個の手順を覚える必要がある／使い始めるには Y を理解する必要がある
• 一本化する／一元化する → すべての X が Y という一つの入口を通る
• 強化する／AI による強化 → X を追加すると Y ができる／X の手順で LLM を使う
• 基盤／基礎となるロジック → 基盤となるインフラ層は X／これが成り立つ前提は Y

評価調／進行役調の表現

• 非常に価値がある／とても価値がある → どの点で価値があるか、具体的な理由を示す
• 極限まで／究極の体験 → 具体的な指標に置き換える。たとえば、遅延をどれだけ下げたか、手順を何段階減らしたか
• 滑らか／スムーズ → 具体的な制約に置き換える。どの手順が以前はボトルネックだったのか、今はどの手順を省けるのか
• 深く統合する／深く連携する → 統合の具体的な範囲を示す
• ワンストップ → A の入口で B / C / D を完了できる
• 破壊する／再構築する → 原則として使わない。どうしても使うなら、変更前と変更後を比較する

根拠を優先した文章

コードやアーキテクチャについて書くときは、実装の詳細を抽象的な結論にそのまま置き換えないでください。

推奨する順序は次のとおりです。

コード / issue / trace / metric -> 全体的な傾向 -> 抽象的な整理 -> 設計判断

たとえば、次のようには書かないでください。

現在のコードでは、この経路はすでに明らかです。

代わりに、次のように書くとよいでしょう。

今日のコードに目を戻すと、比較的安定した全体的な傾向がいくつか見えてきます。これらのモジュールをたどっていくと、まず比較的安定した構造を整理できます。その結果、先に述べた複数の機能も、今後さらに受け入れていくのに適した実装箇所がいくつか見えてきます。

読者を意識した説明

技術的な意見の相違の多くは、「作者が、読者もすでに自分の前提を受け入れていると思い込む」ことから生じます。読者がどう考えるかをまず推測し、そのうえで誤解を解きほぐすとよいでしょう。

よく使う言い回しは次のとおりです。

• まず定期的な巡回を思い浮かべるかもしれません。たとえば……
• この方向で考えていくと、私たちがより重視しているのは……だと分かります
• このように理解すると、今回の設計の境界により近づきます

次のような quote を続けるのに適しています。

一つの巡回タスクが、予定された周期に従って各指標をスキャンする方法

その後、本当に議論したい問題に移ります。

継続的に流入する生ログを、書き込み経路を遅くすることなく、通知すべきアラートと判定するにはどうすればよいか

Few-Shot の修正例

以下の例は、抽象的なルールよりも重要です。似た文型に出会ったら、まずこの方法に沿って修正してください。

1. 英語の real / realize / reality を中国語にそのまま訳さない

元の文：

アラートルールを複数の収集先に接続すると、粒度の問題がすぐに現実味を帯びます。

問題点：

• ここでは 現実味 は適切な述語ではありません
• 主語は 粒度の問題、述語は 帯びる であり、組み合わせが不自然です
• 制約を説明するのではなく、感想を述べているように見えます

修正例：

アラートルールを複数の収集先に接続した後は、ルールの粒度を制御することが重要になります。

このように修正する理由：

• まず条件を書く：複数の収集先に接続した後
• 次に対象を書く：ルールの粒度を制御すること
• 最後に判断を書く：重要になります

2. 制約の代わりに中身のない評価語を使わない

原文：

この組み合わせはとてもスムーズです。

問題点：

• とてもスムーズ は感想にすぎず、情報がありません
• 読者には、コスト、経路、レイテンシ、モジュールの境界のどこがスムーズなのか分かりません

書き換え：

この組み合わせは、実際の役割分担により近いものです。

または：

この組み合わせなら、ログ書き込みの経路とアラート判定の経路を分離できます。

このように書き換える理由：

• 役割分担を直接説明する
• または、構造がどう変わるかを直接説明する
• 技術的な判断を、作者の主観的な感想で置き換えない

3. 対立構文で無理に強調しない

原文：

これを真剣に見るべき理由は、宣伝文句ではなく、一連の収集とアラートの仕組みが非常に完全な形で組み立てられていることです。

問題点：

• ……ではなく…… は説教調になりやすいです
• 読者が本文に入る前に、作者の立場に誘導されてしまいます

書き換え：

より詳しく見ていく価値があるのは、一連の収集とアラートの仕組みが比較的完全な形で組み立てられている点です。

このように書き換える理由：

• 対立構造をなくす
• 文の強調は残す
• 読者が後続の内容に入りやすくなる

4. つなぎの文で内容を代用しない

原文：

ここまで話したところで、アラートの重複排除に関するモデルも一緒に見ておくべきです。

問題点：

• 司会者のような口調で、技術文書にはふさわしくありません
• この文を削除しても、論証の情報は失われません

書き換え：

アラートの重複排除に関するモデルも、あわせて検討する必要があります。

このように書き換える理由：

• すぐに本題に入る
• つなぎの文で本文のスペースを使わない

同様の文は、やわらかく書き換えるのではなく、そのまま削除します。

原文：

まず「圧縮」ということだけを取り出して話します。

問題点：

• 司会者のような文で、新しい情報を提供していません
• 削除しても、後続の論証に影響はありません

対応：

そのまま削除し、次の文を段落の冒頭にします

5. 「文章を進行させる」文を本文に書かない

原文：

この図が示したいことはとてもシンプルです。

問題点：

• 進行役のような文で、図の外にある新しい情報を提供していません
• 読者が本当に必要としているのは図の後に示される結論であり、作者による導入ではありません

対応：

そのまま削除し、次の文で図の構造上の関係を直接説明します

原文：

次に、この節で本当に考えたい問題に入ります。

問題点：

• 話の流れを誘導するだけで、事実を補足していません
• 次の文がすでに問いの形なら、この文を置く意味はありません

対応：

そのまま削除するか、次の文を完全な問いの形にします

原文：

最後は、少し控えめな一言で締めくくれます。

問題点：

• 作者自身の執筆上の動きを管理するだけの文です
• 本文で、作者が「今から締めくくろうとしている」ことを明かす必要はありません

対応：

そのまま削除し、引用または結論を直接示します

6. 論証に順序があるなら、そのまま 1. 2. 3. 4. と書く

原文：

第一に、収集元は多いものの、ログは最終的にアラートエンジンに集約されます。 第二に、収集層はすでにログの正規化を担っています…… 第三に、アラートエンジンには、もともと一連のルールの境界が備わっています…… 第四に、周辺モジュールからは、価値のあるイベントがすでに数多く出てきています……

問題点：

• 4つの段落を個別に書くと、読者には並列の論拠だと分かりにくくなります
• 論拠の順序と論証の強さが目立ちません

書き換え：

1. 収集元は多いものの、ログは最終的にアラートエンジンに集約されます。
2. 収集層はすでに、ログの正規化、フィールドの抽出、タグの挿入、ソースのラベル付けを担っています。
3. アラートエンジンには、安定したルールの境界がすでに備わっています。
4. 周辺モジュールからは、十分な数のイベントと状態がすでに提供されています。

このように書き換える理由：

• 論証の順序を明示できます
• それぞれの点が単独でも成立します
• 後続の内容で参照しやすくなります

7. 指標名と動作を表す語は、同じ意味体系にそろえる

原文：

最初の命題群はコンバージョン率に近いものです。異なる source の種類がシステムに入った後、どれだけが dedupe で除かれ、どれだけが cooldown で止まり、どれだけが policy に受け止められ、最後にどれだけが本当に1件のアラートに昇格するのでしょうか。

問題点：

• コンバージョン率、dedupe で除かれる、止まる、受け止められる、昇格する と、複数の語彙体系が混在しています
• 指標名と動作を表す語が、同じ意味体系にありません

書き換え：

1. 流通性を計算します。 異なる source の種類がシステムに入った後：
   • どれだけが dedupe で選別されるか
   • どれだけが cooldown で集約されるか
   • どれだけが policy に該当するか
   • 最後にどれだけが1件のアラートに昇格するか

このように書き換える理由：

• まず指標名の 流通性 を定めます
• 次に動作を表す語を 選別／集約／該当／昇格 に統一します
• この一連の語は互いに補い合うため、意味が食い違いません

8. 表面上はモジュールについて話していて、実際には概念を位置づけている場合は、まず簡潔な図を示す

原文：

収集の入口からアラート判定層まで…… その後、アラートエンジン、収集層、ルールモジュールの説明を始める……

問題点：

• 読者は、この節が何に答えようとしているのか、まだ分かりません
• 「モジュールの説明」が「既存システムの復習」になりやすいです

書き換えの構成：

1. まず問題を明確にします。この節は表面上はアラートエンジンについて述べていますが、本当に答えるべきなのは、重複排除モジュールをどこに配置するかです。
2. 簡潔な mindmap で周辺モジュールを整理します
3. 次にライフサイクル図を示します
4. 最後に 1. 2. 3. 4. の論拠を記述し、概念を既存のシステムに位置づけます

このように書き換える理由：

• 図で動作の仕組みを示します
• 本文で設計上の問いに答えます
• モジュールの説明が概念の論証を圧迫しません

9. TL;DR では、着想のきっかけ、問題の定義、モジュールの設計の順に説明する

原文の構成：

現在のシステムには、活用できる情報源がすでに数多くあります…… 私たちの仮説は…… この判断に基づき、私たちの決定は……

問題点：

• システムの現状から始まるため、主眼が平坦になります
• 着想のきっかけが先に示されないので、読者がすぐに問題に入れません
• この判断に基づき、私たちの決定は も、少し進行役のような口調です

より適切な構成：

第1段落：まず、外部から得た着想や上流プロジェクトによる変化を説明します 第2段落：ログ、メトリクス、trace、イベントなどの入力がすでに存在することを述べ、次にシステムが整理すべきものは、繰り返し発生し、集約が必要な重複アラートであると説明します 第3段落：新しいモジュールの設計と、メッセージキューや非同期コンシューマーフレームワークなどのアーキテクチャ上の決定を直接示します

例：

上流のある監視プロジェクトをきっかけに、別の形のアラートが見えてきました…… 現在のシステムにも、すでに十分な入力元と状態の情報があります…… ここでは、新しいモジュール設計を提案します……

このように書き換える理由：

• 第1段落で背景と動機を示します
• 第2段落で問題を定義します
• 第3段落で決定を直接示します
• 読者は3つの段落に目を通すだけで、文書全体の主軸をつかめます

10. 作者の感想を技術的な判断として書かない

原文：

この組み合わせはとてもスムーズです。

原文：

この経路はとても明確です。

原文：

これはすぐに現実的な問題になります。

問題点：

• スムーズ、明確、現実的 は作者の感想であり、技術的な判断ではありません
• 読者には、何がスムーズなのか、どこが明確なのか、制約は何なのか分かりません

書き換えの方針：

まず条件を書きます 次に対象を書きます 最後に判断を書きます

例：

アラートルールが複数の収集元に接続されると、ルール単位での制御が重要になると考えられます。

11. 構造を比喩的な動作として書かない

原文：

散らばって出てきました

原文：

集めてきます

原文：

1つの層へと収束させます

原文：

展開していきます

原文：

action skipped で止まります

原文：

failed に落ちます

問題点：

• こうした表現が自然に思えるのは、作者がシステムを「流動するもの」として捉えているためです
• 中国語で書くと、主語と述語、目的語の関係が成り立たないことがよくあります
• 「状態」「構造」「結果」を「位置」や「動作」として誤って表現してしまいます

書き換えの方針：

• 提供しました
• 整理しました
• 同じ層に集約して処理します
• 後続の処理を追加します
• 最終的に action skipped が生成されます
• 最終的に failed が生成されます

リスト、引用、流れ

「文章らしく」見せるために、すべてを無理に段落形式の文章にしないでください。内容がもともとリスト形式に適しているなら、そのまま列挙したほうが明確です。

リスト形式に適した内容：

• 設計目標
• 仮説
• モジュールへの影響範囲
• 補足が必要な実装項目
• 評価命題
• 適用／非適用のシナリオ

一連の判断に論証の順序がある場合は、複数の段落に分散させず、1. 2. 3. 4. の形式で示すことを優先します。

引用に適した内容：

• 強調したい命題
• 読者がまず思いつく可能性のある別の問題定義
• サイバネティクス／システム論／issue からの抜粋にある重要な文

矢印で示すのに適した内容：

• event -> dedupe -> alert
• background -> hypothesis -> answer
• collect -> match -> notify

モジュール単位の記述

抽象的な話だけでは内容が曖昧になりがちです。コードの話だけでは設計の視点が失われます。社内向けの技術文書では通常、次の2つの層をあわせて示す必要があります。

• 抽象層：概念、境界、意味、主張
• 実装層：モジュール、型、収集器、ルール、ストレージ、trace、eval

実装層について書くときは、できるだけモジュールの全体像を示します。

• すでに存在するモジュール
• 局所的な規則性だけが見られるモジュール
• 後続の代替実装としてより適しているモジュール
• 補償、移行、圧縮、疎結合が必要な箇所

「改修」や「実装の補足」について述べる段落では、スキャンしやすいブロックを優先して示します。たとえば次のようにします。

補足実装が必要になる可能性のある項目：

• アラートストレージ層の CRUD 拡張
• アラートオーケストレーションを inline から非同期コンシュームに移行
• tracing の圧縮および集約戦略
• 可観測性パネルにおける経路の表示と命題の集約

トーンの調整

社内レビュー、リーダー、現場の開発者を対象にする場合は、「一緒に問題を整理する」トーンを基本にします。

• 断定を減らし、推論の道筋を示す
• 絶対的な副詞を減らし、まず、できます、一時的に、この観察に沿って などを使う
• 裁くような文を減らし、説明する文を増やす
• 「作者が勝った」ような結びを避け、読者がそのまま読み進められる結びにする

Editing Checklist

交稿前，逐项扫一遍：

• 有没有没有证据支撑的强判断
• 有没有 不是……而是…… 一类对立句法
• 有没有 很清楚 / 说明了 / 显然 / 真正 这种抢结论的词
• 有没有把代码直接翻译成抽象结论
• 有没有只讲概念，不讲模块和影响面
• 有没有该列清单的地方却硬写成长段
• 有没有前文提出的猜想，后文却没有 callback
• 指标名、动作词、状态词有没有混用，名词和动词是不是同一套语义系统
• 有没有过场句在替内容占位置；如果删掉一句话不影响论证，就直接删掉，不改写成另一句过场话
• 中文引号有没有统一成 「」

Default Prompting Pattern

收到草稿时，先做三件事：

1. 标出文中最强的几个判断
2. 检查这些判断有没有 callback 或 evidence
3. 按 背景 -> 猜想 -> 解答 -> 回指 重排结构，再改句子

如果需要给出改写建议，优先直接改成可用的句子，不要只做抽象点评。