reviewing-technical-prose

技術的な文章のレビュー

必須の前提知識: technical-writing スキル。これには references/style.md（禁止される構文）と references/truth.md（主張に関するルール）が含まれます。

概要

編集とは診断です。すべての編集は、それが修正する具体的な欠陥を特定します。それを修正する最小の編集が勝ちます。欠陥を特定せずに、自然な、または承認済みの表現を書き直すこと自体が欠陥です。

要約ではなく、文書全体をレビューしてください。

いつ呼び出すか、呼び出さないか

他の人が書いた技術的な文章をレビューまたは書き直すとき、文書に関する指摘レポートを作成するとき、そして自分で書いたものを納品する前の最終パスとして呼び出します。コードレビュー（その中の文章のみを対象とする場合を除く）では呼び出さないでください。また、レビューのパスを、決着済みの決定を蒸し返したり、スコープを広げたり、文書を自分の好みに合わせてスタイル変更したりするために使わないでください。

重大度のマッピング

• BLOCKER: ハードルール違反（禁止されたダッシュ、変更履歴のセクション、文章中に現れる納品履歴）および、引用された出典が裏付けていない、または何にも由来しない主張。
• WARNING: 禁止される構文、構造上の欠陥（疑問文の見出し、埋もれた結論、並べ替え可能な段落）、および緩くしか裏付けられていない主張。
• OBS: 曖昧さ、磨き込みの不足、および注意深い著者ならおそらく気づくであろうあらゆること。

他の人の文章を書き直す

すべてのルールに優先する要件が一つあります。内容は同一のままに保つことです。この順序で作業します。

1. 原文を読みます。禁止される構文と語彙選択の違反をすべて印付けします。

2. ある版を書きます。それを音読します。

3. 三つのコントロール質問をします。

   • どの文がまだ言語モデルのように響きますか？
   • 書き直しによって、事実、数値、日付、名前、出典、または主張が追加または脱落しましたか？
   • 書き直しによって、削除されたパターンが新たな修辞形式で再現されていませんか？

   書き直した段落を、それが原文であるかのように再スキャンします。

4. コントロール質問が明らかにしたものを修復します。追加も脱落も、どちらも誤りとして数えます。たとえそのほうが文章がよく読めてもです。

文を完成させるために事実を追加してはいけません。著者に尋ねるか、より単純な文を選んでください。二度試しても文がぎこちないままなら、その主要な点を中心に段落全体を書き直します。書き直すのは流れる文章だけです。コードブロック、frontmatter、表のデータ、リンク先はそのままにします。

• 書き直しは文書の言語を保ちます。 オランダ語の文書はオランダ語で返され、構造と真実のルールはいつもどおり適用されます。英語固有の語彙チェックは、その言語に独自のリストがあれば、それに置き換えられます。
• 著者に連絡が取れる場合、差分が提案となります。 その人のテキストを上書きする前に、書き直しを見せます。リポジトリでの無人の場合、コミットが提案となり、レビューが同じ役割を果たします。

原文が回収可能な主張を何も述べていない場合（セットアップ、注釈、意味だけの文）、正しい書き直しは削除に加えて、印を付けたギャップ（**[input wanted: <the claim the sentence should make>]**、コアスキルの **[source wanted: ...]** の主張レベルの兄弟分）を、本当の主張が立つべき場所に置くことです。印を付けたギャップだらけの書き直しは、主張のない原文に対する意図された結果であり、失敗ではありません。

そのままにしておくべき指摘

禁止構文のリストはそれ自体では何も証明しません。どのパターンも優れた人間の文章にも現れます。同じ段落内で複数の兆候が重なった場合にのみ指摘してください。

• 磨かれた文法と一貫した書式。
• 繰り返される一文の書き出し：その繰り返しが何も付け加えない場合にのみ修正します。
• 強調のための短い一文：問題となるのは断片の羅列だけです。
• 一般に形式ばった語：リストは特定の語を挙げているのであり、すべての形式ばった語を簡素化する必要はありません。
• 事実に基づく対比：「タグを設定するのはパイプラインであり、開発者ではない」は主張であって、対句ではありません。
• 読者が本当に検討する真剣な代替案：それは文書に属します。
• 何かを限定する修飾語：範囲、前提、安全性や法務に関する注記は残します。削るのは積み重ねだけです。
• マイグレーション文書やリリースノートにおける以前の状況への言及：そこでは変更そのものが主題です。
• 引用された語：引用、タイトル、その語を論じる例の中は決して書き換えません。
• 説明する比喩：その周りの装飾だけを削ります。
• 意図的な不格好さ：明確な断片や歪んだ文は、磨くことができたというだけでは欠陥ではありません。

レビューレポート

• 判定は最初の行に、指摘は最も重大なものから順に。
• それを用いるレポートで定義される重大度の語彙：BLOCKER（進行不能）、WARNING（手戻りの可能性が高く、修正すべきだがブロッキングではない）、OBS（言及に値する）。
• すべての指摘：欠陥を述べる一文、位置（file:line、セクション、タスク ID）、提案する修正、および確信度。
• 名前を付けた空の場合（「FINDINGS: none」）。
• コードと矛盾する文書の主張は文書側の欠陥です。矛盾する情報源を添えて報告してください。たまたま気づいた無関係なバグはあなたの指摘ではありません。
• 再レビューには残っているものだけを列挙します。
• 良い点は認めます。

納品チェックリスト

文書を出す前に：

• 同じディレクトリの既存文書と整合しており、README.md の索引があればそこに追加されている
• em ダッシュ、en ダッシュ、-- がない；変更履歴セクションや「最終更新」フィールドがない；本文中にチケットキー、フェーズ、SHA がない
• 禁止構文がない（technical-writing スキルの references/style.md）；少なくとも要約と結びの段落を確認する
• 見出しが内容を示す：疑問形でない、「X とは何を意味するか」でない、見出しがその最初の文で繰り返されていない
• 結論を先に、文書、章、段落の各レベルで
• 手順：1 文につき 1 つの操作、行為者を明示
• 文書が提案または決定する箇所：自明でない選択にはすべてその根拠と真剣な代替案が記録され、コストも記載されている（利点だけでなく）
• 事実と提案が区別できる；推定にはラベルが付き、不明な点は明示的に不明とする
• 数字を伴うすべての主張が、文書内で名前を挙げられた情報源にたどれる
• 参照をたどって確認：章番号、相対リンク、ファイル名が実際に存在する
• 用語が一貫し、初出時に定義されている；概念ごとに 1 つの用語
• 音読：少なくとも要約は；断片の羅列がない、同じ書き出しの文が 3 つ続かない
• 冒頭と要約で名前を消すテスト：製品名を削除しても、初見の読者がそのテキストが何についてかを判断できる
• 冷えた状態で読める、通して読める：それを生み出した会話やフィードバックのやり取りを一度も見たことのない人にとって自然である；全体を通して 1 つの声、継ぎ接ぎの跡がない、なぜこのように文書が書かれたかを説明する文がない
• 書き直しの場合：事実、数字、日付、情報源が追加も欠落もしていない