https://blog.riywo.com/2021/01/how-to-write-high-quality-technical-doc/ [[Ryosuke Iwanaga]]さんが技術文章の書き方についてまとめた記事。著者は文書に厳しい[[Amazon]]の中でも文章の質が高いと評価されている # メモ ### 文章とは - 新しいプロジェクトの骨子を説明する資料 - 会議の叩き台となる 1 枚ペラ - 本番環境に変更を加えるにあたっての包括的な情報や具体的な手順 - 技術仕様を網羅的に説明した一連の文章 ### 抑えておくべきポイント 一言で言うと**輪郭が伝わること。** 具体的には - 文書から得られるアウトプットが明確 - 読み手のレベルによらず一定に伝わる 輪郭が伝わることのメリットは **議論に必要な全員のレベルを短時間で揃えることができる** 点 ### 文章書く前のポイント #### 文書から得られるアウトプットをまず定める > 質の高い文書を書くコツのまず第一であり最も重要なことは、最初にアウトプットを定めることである。つまり、この文書を初めから最後まで読んだ人は一体どんな情報を得られるのか？ということを文書を書く前に決めるのだ。これは Amazon の"working backwards"そのものだ。 アウトプットを定めるとは、会議の理想的な結論から逆算することである。これは[[Amazon]]のプロダクト開発アプローチとして有名な[[Working Backwards]]の考え方そのものである。 #### アウトプットは課題の定義から始める 課題が適切に定義されていなければ、アウトプットの価値は分からない。課題を明確にしておくこと。 ### 文章書く時のポイント #### 文章の存在する目的を冒頭に書く 理由が分かれば読み手との祖語も防ぐことができるので冒頭に書く。 #### アウトプット(結論)を先に書く - 提案文書なら提案 - 変更手順書なら変更のWhat/Why #### 数値を使って説明する 数値は客観性が高いため。 メトリクスを使う場合はそれを参考情報程度にしておく。**メトリクスがなくても文書だけで伝えられることが大事。** #### 箇条書きを乱用しない 文書を速く仕上げるために箇条書きは楽だ。一方、箇条書きのカタマリやインデントは読者に暗黙の理解を強制する。必要なときだけ使おう。 #### 読み手を常に想像する 主観で書くと前提知識が異なるため、特に新しい人は輪郭が伝われないかもしれない。そのような人をフォローできるような文章にする。 - 知識量の多い読み手に対してスキップを促す - 知識量の少ない読み手に対してリンクなどで詳細を提供する #### 細部に目を配る typoやコピペの修正漏れなど。読み手のノイズになってしまうのでエチケットとして必要だ。 ### 議論をスムーズにするために #### 選択肢を可能な限り網羅する 提案された選択肢のみだと読み手は比較ができない。そのため、選んだ理由が気になってしまい納得感も薄れる。 #### 自分の意見を表明する 選択肢を書いた上で自分の意見は必要。 #### 長くなりすぎない 補足したい情報はリンクやAppendixで補填する。