document-restructuringlisted

# 書き上げた文書を章立てから組み直す **この工程が作るのは、同じ内容を読み手が問う順に並べ直した文書と、前後の値の表である。** 内容を足すことも、書き方のルールを新しく持つこともしない。 | 作るもの | 中身 | | --- | --- | | 組み直した文書 | 章立てを読み手の問う順に並べ替え、長い文を分け、対比と列挙を表にしたもの | | 前後の値の表 | 測った指標を再構成の前と後で並べたもの。目安を超えた項目は理由を添える | ## なぜ別の工程にするか **最初に書き上がる文書は、書き手が調べた順に並んでいる。** 調査は「問題に気づく → 測る → 枠組みを当てる → 結論を出す」の順に進み、文書もその順で書かれる。読み手が最初に知りたいのは 結論であるため、並びが逆になる。 **書いた本人はこの食い違いに気づけない。** 調べた順に読むと筋が通って見える。別の工程として 切り出さないかぎり、組み直す機会が来ない。 ## いつ通すか | 場面 | 扱い | | --- | --- | | 工程として | 文書を作る工程の後、その文書をレビューへ出す前 | | 明示指示として | 書き上げた文書があるとき。種類は問わない（設計文書・課題の本文・Pull Request の本文・説明文書・報告書） | **レビューの前に置く。** 後に置くと、レビュー担当が構成の指摘と内容の指摘を同時に出すことに なり、どちらの指摘なのかが混ざる。構成を整えてから内容を見てもらう。 ## 手順 **4 段を順に通す。** 段 1 と段 4 は同じ指標を測る。 | 段 | 行うこと | 出るもの | | --- | --- | --- | | 1. 測る | 再構成の前の値を取る | 指標ごとの数 | | 2. 組み直す | 章立てを読み手の問う順に並べ替える。**内容を足さない** | 並べ替えた文書 | | 3. 整える | 長い文を分ける。対比と列挙を表にする。語を一意にする | 整えた文書 | | 4. 測り直す | 前後の値を並べ、目安を超えた項目に理由を添える | 前後の値の表 | ### 段 1: 測る **測る手段は対象リポジトリから探して決める。** 候補は順序ではなく一覧である。対象に実在する ものを採る。 | 候補 | | --- | | そのリポジトリがすでに持つ文書の検査の仕組み（設定ファイルや継続的統合の定義から探す） | | そのリポジトリで動く処理系を使い、その場に書く短い集計 | | エディタが備える文字数・行数の表示 | | 手で数える（結論の位置・章の数・章あたりの行数） | **どれも見つからないときは、手で数えられる指標だけを測る。** 測れなかった指標は 「測れなかった」と段 4 の表へ残す。**測れないことを「目安に収まっている」と書かない。** **文の区切り方と字数の数え方は言語で違う。** 対象の文書の言語に当たる `references/lang-<言語>.md` を探して、そのファイルだけを読む。**この文書は言語の一覧を 持たない**（言語を 1 つ足すときに他のファイルを変えないため）。当たるファイルが無い言語では、 区切りの定義をその場で決めて記録へ残し、`lang-<言語>.md` を足す。 ### 段 2: 組み直す **章立てを「章立ての並び」の順に並べ替える。** 段落と文はまだ触らない。 **内容を足さない。** 組み直しと書き足しを同時