先日エンジニア向けドキュメントガイド1の感想メモ(以下、仲田本)書いて、別のドキュメントガイドを昔読んだことを思い出し、当時のメモを見つつ、違いのメモ
本書は「Corg.ly」という仮想サービスのドキュメントをどう作って運用していくか、順を追って説明する。対象がサービスを利用する開発者向けと具体的。なのでガイドも具体的。
そもそも、なぜドキュメントを書く必要があるのでしょうか？ 単にソフトウェアについて知ってほしいからではありません。ユーザーに何らかのタスクを完了してもらいたい、もしくは何らかの方法で行動を変えてほしいからです。そこにはユーザーにとっての技術的なゴールと、ユーザーにたどり着いてほしいという、あなたにとってのビジネス的なゴールがあります。
CHAPTER 1 読み手の理解
開発者向けドキュメントと言っても、いくつかあり、それぞれの役割を明確にしている。
スタートガイドは、より高度なコンテンツへ進む前のスタート地点にもなります。よくあるドキュメント構成の間違いは、ハウツーガイドのような詳細なドキュメントのみを作ることです。しかし、ユーザーがサービスを使い慣れていようが、単に触ってみたいだけであろうが、すべてのユーザーをサポートできるようにしてください。
CHAPTER 2 ドキュメントの計画
チュートリアルが焦点を当てるのは学習ですが、ハウツーガイドはユーザーの実際のコード実装に基づいた内容になります。
CHAPTER 2 ドキュメントの計画
ユーザーが開発を始めると、すぐリファレンスドキュメントに頼り切るようになります。手順書やコンセプトドキュメントは教育や情報提供を扱うのに対し、リファレンスドキュメントは原因と結果を扱います。
CHAPTER 2 ドキュメントの計画
この辺り、一緒くたに混ぜがちだけど、ちゃんと目的に応じて使い分けるべき。
分かりやすいドキュメントを書くのと同時に、サービスが続く限り、書いたドキュメントの運用も大事である。
- サービスのアップデートに追従する: KPEとドキュメント更新がどう管理されているかが紹介されている
- ドキュメントの評価: ドキュメントのメトリクスを取得し分析する
ドキュメントの目的が、ユーザーに何らかの行動変容を求めることなので、ちゃんと「変化したか」を測るのは大事。
仲田本が「良いドキュメントの設計方法」をテーマにしているのに対し、本書は「開発者ドキュメントとは」がテーマなのが違いだろうか。両方とも読みやすかった。無理矢理どっちをお勧めするかと言われたら
- 一般論として良いドキュメントの書き方を知りたい → 仲田本
- 開発者ドキュメントの書き方とその運用を知りたい → 本書
だろうか。なお、訳者が自身ポッドキャストで著者の1人にインタビューしており、背景となる考え方みたいなことが語られていて、こちらも面白く拝聴した。