Writing Tech Text
読者が必要な判断に進める文章を書く。 依頼された範囲で、意味、根拠、確信度を保ちながら構成と表現を整える。
適用範囲と参照資料
PR 本文、ADR、design-doc など、第三者が読む文章を扱うたびにこの skill を使う。 新規執筆、改稿、一文の変更、誤字修正、文章レビューのいずれも対象とし、変更の規模や種類で省略しない。 会話相手への直接返信は、明示された場合だけ対象にする。
構成と論証の見直しを毎回読み、依頼された範囲に適用する。 日本語の文章を扱う場合は、日本語の規範も読む。 英語固有の規範はまだ持たない。
依頼に合わせた使い方
- 短い推敲や表記修正は、その範囲を直接直す。 全文の再構成や事前メモを必須にしない。
- レビューだけを求められたら、本文を書き換えず、理解や判断を妨げる問題を重大な順に指摘する。 箇所、理由、修正方針が伝われば、定型の出力項目を埋める必要はない。
規範の参照を理由に、依頼箇所以外の全文を書き換えたり、全観点への回答や定型手順を求めたりしない。
保持するもの
- 読者に必要な事実、決定、制約、不確実性を残す。 短くするために論証や判断の材料を削らない。
- 推測で書き手の意図を補わず、未確認のことを確認済みとして書かない。 推測、仮説、疑念、反実仮想を断定に変えない。
- 因果や保証を述べるなら根拠と適用条件を示す。 根拠が支える範囲を超えて主張を強めない。
- ユーザーの文体と確信度を保つ。 意味を変える判断が必要なら、推敲に紛れ込ませず、確認点として示す。
- 要求された調査量や報告の詳しさを減らさない。 必要な中身を読者が追える形にする。
読者に合わせた表現
文章全体を見直すときは、表記より先に、何を主張し、何が根拠で、誰に何が変わるのかを整える。
- 読者が最初に必要とする文脈から始める。 実装名や内部の詳細は、理解や作業に必要な分だけ出す。
- 主体、対象、影響範囲を具体化する。 大きな主語、評価語、一般論だけで説明を済ませない。
- 段落、見出し、箇条書きは、情報の関係を読者が追える形にする。 個数や長さを揃えるために内容を分割しない。
- 広く理解される語を使い、独自の造語や気取った表現を避ける。
- 読者の判断に情報を加えない予告、総括、称賛、重複を削る。 機械的な保証や検証の説明も、読者の判断や行動に必要な場合に限る。
セルフチェック
変更した範囲を読み返し、意味・根拠・制約・確信度が保たれ、読者に必要な情報が伝わることを確かめる。 必要な内容を伝えられた時点で完成とし、チェック結果や定型の総括を本文に付け足さない。