Docs for Developers 読んだ

Docs for Developers 読んだメモ。

ドキュメント書き方だけにとどまらず、どのようにドキュメントを改善していくか、誰に向けて書くかなどが書いてあり、非常に面白かった。e34.fm で話していたのを聞いて買った気がする。

特に印象に残ったのは

  • ドキュメントを書く前に誰が読者で、その人はどんなゴールがあるかを考える
  • ドキュメントをいくつかの種類に分けて、伝えたい内容によって変える
  • ドキュメントは公開して終わりではなく、内容についてのフィードバックをもらったり、計測したり、内容が古けれ適宜修正したりする

誰のためのドキュメントか

有用なドキュメントを書くためには読者が誰であり、何を達成したいかを知ることが重要だ。例えば読者が開発者の場合にはコードを含めた説明でも多分通じるだろう。しかし読者がプロダクトマネージャーの場合は通じないかもしれない。また、開発者であっても、シニアレベルかジュニアレベルかで内容違った方が良いかもしれないし、SRE か Application Engineer かで求めている情報が違うかもしれない。これらの違いを理解するために本書では direct interview (対面でのインタビュー)や、survey (アンケートみたいなもの) を薦めている。それらの情報を元にユーザのペルソナを作り、ユーザストーリを作り、ユーザジャーニーを作りと、まるでサービス開発のような手法でドキュメントを作り始めている。自分の中ではこの部分が一番印象的だった。

伝わりやすいドキュメントの種類を選ぶ

コンテンツタイプを変えることによって、伝えたい内容をより効率的に伝えることができる。その文書がチュートリアルなのか、API reference なのかで章立てや、書く内容が変わっている方がよい。本書では大きく分けてコンテンツタイプを以下の6つに分けている。例えば Procedural documentation というは、チュートリアルや アプリケーションのインストール方法の説明などの文書。読者は自分の問題(アプリケーションを使い始めたいがどうすればいいかわからない。など)を素早く、しかもなるべく簡単に解決するためにこのタイプのドキュメントを読むだろう。ということで、この文書は長々とした説明は避けて、簡潔な手順書のような構成が望ましい。自分はドキュメンを書くときにどんなタイプの文章かというのを明示的に考えたことがなかった。この部分が言語化されていて感動した。

  • Code comment
  • READMEs
  • Getting started documentation
  • Conceptual documentation
  • Procedural documentation
    • Tutorial
    • How-to guides
  • Reference documentation
    • API reference
    • Glossary (用語集)
    • Troubleshooting documentation
    • Change documentation

ドキュメントを最新に維持する

ドキュメントは公開したら終わりではなく改訂が必要だ。プロダクトチームは機能を追加したり、削除をしたりするだろうし、API reference に書いてあるメソッドは書き換えられかもしれない。ドキュメントもこれらの変更と共に変更されていく必要がある。本書では機能を設計/変更する段階で、それがユーザに及ぼす機能などと同等に、それが”ドキュメント”にどのように影響があるかも考えるべきだと言っている。また、それぞれのドキュメントのオーナーを決めて、そのオーナーが責任を持って文書のアップデートやレビューをした方がよい。