読み手のために書く は何をしますか？
あなたの読み手はその場にいませんでした。分野は知っていても、あなたのプロジェクトは知らず、斜め読みします。語彙の選択には plain-words を適用してください。
- 既存の論文、レポート、ページの編集、校正、クリーンアップ：以下のルールをチェックリストとして
references/editing-pass.mdに従ってください。 - 論文の執筆または編集：
references/paper.mdも読んでください。
順序
- 発見事項を先に述べる： 何が起こったのか、そしてその規模。新しいアイデアや能力を見出しにします。比較は、それが貢献である場合にのみ先に述べます。導入が必要な場合にのみ、問題提起から始めます。決して一般的な導入から始めないでください。プロジェクトの履歴や実行したログを説明しないでください。
- 見出しは主張を述べる： レポートでは（「価格分析」ではなく「より安いプランがより多く売れる」）。長いレポートは発見事項の番号付きリストで始めます。
- 要約とTL;DR： 高いレベルに留めます：発見事項を言葉で、読者が引用する数字を、nullを言葉で、それぞれがなぜ重要なのかを。求められた長さに合わせてください。読者が覚えられる平易な主張で終わります。
- メールと引き継ぎ： 短い決定リストです：何をすべきか、各修正の難易度、最も手作業が少ないオプションはどれか。
- 本文は独立している： すべての用語と比較対象を、本文中で最初に登場する場所で定義します。決して最初に付録で定義しないでください。長いレポートは短い用語集で終わります。
内容
- すべての数値に比較対象を付ける： 「25.6%の精度（チャンスレベルは10%）」。
- 発見事項の大きさを、たとえ小さくても述べる。
- 発見事項ごとに1つの実例を示す。 ケーススタディ、驚き、確認された否定的な結果は残します。
- 手法は、最初に登場する場所で一度だけ説明する： 方法について一行、なぜかは、読者が疑問に思ったり誤解したりする場合にのみ説明します。母集団や分母を定義する除外条件は開示します。ルーチン的な選択を擁護しないでください。
- 発表の場やユーザーが求めない限り、自身のプロセスに関するコンテンツ警告や注釈は付けない。 しきい値やサブセットを結果を見た後に選んだ場合は、そのルールを一度だけ平易に述べてください。
- 限界は、それが限定する主張の横に一度だけ述べ、それが読者の信じるべきことを変える場合にのみ述べる。 結果を定義する条件（「2024年のみ」など）は維持します。ロバスト性チェックの下での単一の僅差は見出しを格下げしませんが、逆転は格下げします。
- 過剰主張を迂回表現で和らげるのではなく、狭める： 確かな部分は残し、不安定な部分は削除します。
- 発見事項を台無しにしない。 データが示す以上に譲歩しないでください。読者が信じるべきことを変えない限り、誰も求めていない対照を加えないでください。チェックによってストーリーが弱まる場合は、迂回表現や削除をする前に、分析の修正や拡張を提案してください。自分で分析を変更しないでください。
- 密集したブロックは避ける。 段落は1つのポイントを述べ、一度読めば早く理解できるようにします。発見事項や条件が積み重なっている段落は分割します。数値の羅列は表またはリストにします。箇条書きは項目が並列の場合に適しています。
- 一つのストーリー。 サイドストーリーは削除します。二次的なチェックと例外は本文で一文にします。詳細は付録に回します。
- 同じもの同士を比較する。 異なるデータセットや人物からの数値は、それぞれ独自の文または表にします。あたかも一方が他方を引き起こしたかのように並べてはいけません。
- すべてがそれ自体を正当化できなければならない。 すべての単語、文、段落、リスト項目、セクション、表の列、図のパネル、キャプションの節は、読者の信じるものや読み方を変えなければなりません。それぞれについて問いかけてください：それがなかったら読者は何を失うか？何もなければ、それを削除します。圧縮しないでください。
- それぞれのことは一度だけ言う。 数値は表か本文のどちらかに配置し、両方には置きません。本文か付録のどちらかに配置し、両方には置きません。発見事項は一度完全に述べます。要約、序論、概要はその主要な数値のみを繰り返します。
- ソースにないものは追加しない。 引用や結果を決してでっち上げないでください。著者用にマークされたプレースホルダーを残してください。
図と表
- 各パネルは、本文ではうまく伝えられない1つのポイントを伝えます。指標、良い方向性、ベースラインを明確にします。
- コードではなく実名、最もシンプルなチャート、タイトル付きの軸、キャプションや本文と一致する1つのラベル体系。系列の名前の横に直接ラベルを配置します。
- すべてのサブセットを示すか、それらを選んだルールを明記します。
- レポートでは、図のタイトルは何が示されているかを示します。キャプションはその読み方を示し、方法を繰り返しません。
引き渡す前に
読み手になったつもりで読んでください。各文について：それがないと読み手は困るか？各数値は「何と比較して」と言っているか？その後、plain-words を実行してください。数値を変更しないでください。何かが不足している場合や2つの数値が矛盾する場合は、ギャップを埋めるのではなく、著者に伝えてください。