文書から得られるアウトプットが明確で、読み手のレベルによらず一定に伝わること
この一文に大体このエントリで伝えたいことが集約できている。質の高い技術文書とは、誰が読んでもハッキリとした輪郭で必要十分な情報が伝わるものである。
文書から得られるアウトプットをまず定める
質の高い文書を書くコツのまず第一であり最も重要なことは、最初にアウトプットを定めることである。つまり、この文書を初めから最後まで読んだ人は一体どんな情報を得られるのか？ということを文書を書く前に決めるのだ。これは Amazon の"working backwards"そのものだ。
アウトプットは課題の定義から始める
具体的なアウトプットは文書毎に当然異なるが、重要な共通点として、そもそもその文書がもたらすものによって一体どんな課題を解消しようとしているのかをまず定めることが重要だ。これは working backward の本質でもあり、この過程で、一見解くべき課題に見えた A が実は根本的には B を解消しないといけないという事実が分かったり、実はそもそも課題なんて存在しなかったということが分かることもある。
箇条書きを濫用しない
箇条書きは短文で済むので文書を速く仕上げることができる一方で、行間を読むことを読み手に強制する。例えば、インデントの意味や、項目の順番の意味、実は 2 つの項目がつながって一つのことを書いている、などなど。これは何度も繰り返すが読み手によって得られる情報がブレてしまいがちだ。効果的なポイント以外では無闇に使わず、文章で伝えたい内容をハッキリと書いた方が良い。
長くなりすぎない
文書が全体が長すぎると、そもそもミーティングの時間内(議論の時間を除く)に読みきれない。現場の技術者が日々扱うレベルだと、15-20 分程度で読み切れるボリュームが理想的だ。文書というのは書き込めば書き込む程正確さを増すのでどうしても細かく書きたくなってしまうが、真に詳細な部分はコードレビューや変更手順レビューで確認していけばよいはずだ(実際コードを書いてみて初めて分かることというのももちろん多い)。質の高い技術文書はこの解像度のコントロールが適切で、かつ場合によって様々な別の文書にハイパーリンクしていくことで、足りない情報を必要に応じて補える様にしている。細かすぎるが書き留めておきたい情報は、Appendix という形で本体とは別で添付しておくのも一つのやり方。