最後まで読まれる技術文書の書き方
最初の読者は上司ではなく、三か月後にこの文書を見ながら作業する同僚です。その人が何を決めるために読むのかを先に考えます。
進め方
散らばったメモを使える構成にする
メモ、議事録、リンクをまとめて「散らばった考えを構造化する」に渡します。主旨を一文で、三から五つの部分とそれぞれが解く問い、各断片の配置、重複や矛盾する考えの指摘を求めます。構成を確認してから書き始めると、大きな手戻りを避けられます。
見出しで読者に要点を示す
草稿を「長文に見出しを付ける」に渡します。段落を均等に切るのではなく、話題が本当に変わるところを先に示させます。見出しは八から十四字の平叙文にし、見出しだけでその節が何に答えるか分かるようにします。主題を名付けられない段落は統合するか削り、追加・変更した見出しを一覧で出させます。
主張と根拠を一文ずつ突き合わせる
判断を含む段落を「主張と根拠の強さが合っているか」に渡します。事実、傾向、因果、予測を区別し、根拠の種類を分類し、一つの事例で「すべて」を支えている箇所や、相関を因果として示している箇所を指摘させます。ずれがある主張には、表現を弱めるか根拠を足す提案を求め、本文の書き換えはさせません。
読者を決めて書き直す
読者をプロダクト担当、顧客、経営層のどれかと明示し、技術的な部分を「技術文書を非技術者向けに書き直す」に渡します。冒頭の一文で、それが読者にとって何を意味するかを伝えます。専門用語は初出時に日常の経験で説明し、制約、失敗時の挙動、数字は残します。曖昧な点と欠けている情報は「要確認」として別に挙げます。仕組みを比喩で置き換えません。
せっかちな読者で試す
最後に「いつでも閉じる読者を演じる」で読者像を指定します。どこまで読んで閉じるか、どの一文で集中が切れたか、読者の疑問に答えていない箇所はどこか、著者自身が考え切れていない論点はどれか、半分に削るならどこかを答えさせます。結果に従って削り、書き足しません。
使うプロンプト
よくある質問
技術文書はどのくらいの長さが適切ですか
読者がその文書で何を決めるかによります。必要な場所で止まり、答えを見つけられることのほうが長さより重要です。ステップ5を実行すると、削った段落は読者も読まない部分だったと分かることが多いです。
構成図は AI に描かせてもよいですか
構いませんが、先にステップ1と2で構成と見出しを固めます。そうしないと図も散らかった思考につられて乱れます。図の矢印は、本文に対応する仕組みの説明があるものだけにします。
非技術者向けに書くとき、リスクは削りますか
削りません。ステップ4では、制約、失敗時の挙動、数字を残し、実装の詳細だけを読者が対応づけられる結果に置き換えます。リスクを消した文書は、いざ問題が起きたときに信頼を失います。