最近知った興味深いPodcast e34.fm で紹介されていたので興味を持って読んでみた本「Docs for Developers: An Engineer’s Field Guide to Technical Writing」に関するメモ。
2023/3追記：翻訳されたようだ。ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング
この記事の目次
- 「Docs for Developers」はどんな本なのか
- 全般的な感想
- 各章に関する覚え書き
- Front Matter
- Chap 1. Understanding your audience
- Chap 2. Planning your documentation
- Chap 3. Drafting documentation
- Chap 4. Editing documentation
- Chap 5. Integrating code samples
- Chap 6. Adding visual content
- Chap 7. Publishing documentation
- Chap 8. Gathering and integrating feedback
- Chap 9. Measuring documentation quality
- Chap 10. Organizing documentation
- Chap 11. Maintaining and deprecating documentation
- Back Matter
「Docs for Developers」はどんな本なのか
「プロダクトに付随する」ドキュメントの作成に関して書かれた本。架空のプロダクト、犬の鳴き声を人間の言語に翻訳するAPIサービス「Corg.ly」の話を織り交ぜて語られているので、従来イメージの設計書とかマニュアルといったイメージではなく、まさに開発者が普段目にするようなプロダクトに付随するテクニカルドキュメントの作成について書かれているといっても良いだろう。
著者達は著名なテック企業でテクニカルライティングを実際に行ってきた人々。Googleで活躍した人もいるし、驚くことにGDSのテクニカルライティング責任者だった人までいる。ものすごく豪華なメンバーなんじゃないかと思う。
全般的な感想
「Docs for Developers」とあるように、開発者向けのドキュメントを書く方法について書かれているという点が重要だろう。とはいえ非常に示唆に富んでおりいろいろと応用はできそう。読んで良かったと思うし、ドキュメンテーションに苦労しそうなプロジェクトにぶちあたった時には再び手に取りそうな予感がある。
各章に関する覚え書き
Front Matter
- 文書作成の優先順位を下げたり、省略されたりするのは、我々の多くがそれを行う方法を知らないからだ
- 「優れたコードはそれ自身がドキュメントである」という話はあるが、一方で十分な複雑さと規模をもつプロジェクトにとっては、人間が読める形式のドキュメントは必要だ
Chap 1. Understanding your audience
- 「知識の呪い（The curse of knowledge）」人間は他の人が自分と同じ知識を持っていると想定しやすい。
- 呪いを解き、効果的なドキュメントを書くには、ユーザーへの共感が必要。本章では呪いを解き、ユーザを理解する方法を示す。
基本的にはドキュメントそのものをプロダクトと見なして、ペルソナ、ストーリーマップ、ジャーニーを整理していくという戦略が示されている。
Chap 2. Planning your documentation
ソフトウェアプロダクトによくあるドキュメント類を列挙していて（網羅性がすごいと思う）それを見ながら文書化計画を立てる話。
紹介されているドキュメントの一覧が良かった。説明も素晴らしい。
- Code comments
- READMEs
- Getting started documentation
- Conceptual documentation
- Procedural documentation
- Tutorials
- How-to guides
- Reference documentation
- API reference
- Glossary
- Troubleshooting documentation
- Change documentation
Chap 3. Drafting documentation
「書くことに関して最も難しいことの1つは、空の文書に立ち向かうことです」
というわけで、とても詳しいドラフト文書の書き方である。白紙のファイルに文章の目的を描くところから、目次、本文といった手順が述べられていて、もう完璧。
あと興味深いのは、以下の真実についての立ち向かい方に関する言及である。
- 読者は情報を探してあなたのドキュメントに来ます
- 読者はあなたが書いたものをほとんど読みません
この対策に関する観点はちょっと新鮮だった。
Chap 4. Editing documentation
「編集とは、ドキュメントを調べて、ユーザーのニーズを満たしていることを確認するプロセスです」
「ドキュメントの編集は、コードのテストとリファクタリングのようなものであり、同様に重要です」
文書の編集に関する説明。なお本書では「執筆」と「編集」を明確に別のプロセスとして定義しており、また効率性とレビュー品質向上のために分割することを推奨している。
その上で本章では具体的なチェックリストなども示されている。
Chap 5. Integrating code samples
「コードサンプルは、効果的な開発者向けドキュメントの重要な部分です」
本書の想定がAPIを利用して活用するプロダクトであるということもあり、ドキュメントとしてのコードサンプルについて説明している章。良いコードサンプルを作成するTipsなど。
Chap 6. Adding visual content
「絵は千の言葉に値する」
単一の画像は、認知処理が少なくて済み、脳がつながりを描くのに役立ち、書かれたテキストよりもはるかに迅速に理解を得ることができます。また、画像と一緒に提示すると、情報をよりよく覚えることができます。情報を聞くと、その約10％しか思い出せません。ただし、その情報に画像が付いている場合は、65％を覚えています。
というわけで、ドキュメントにおけるビジュアル活用についての説明。通常の図だけではなく、スクリーンショット（有用とするためにはいろいろな注意点がある）やビデオコンテンツに関する留意点など、学びの深い章である。
Chap 7. Publishing documentation
作成したドキュメントの公開に関して書かれている章。基本的にはプロダクトリリースと同じような、「コンテンツ（ドキュメント）リリースプロセス」の構築が推奨されている。もちろん、これにはリリース前のテストも含まれている。
Chap 8. Gathering and integrating feedback
ドキュメントはユーザーとのコミュニケーションの主要な方法であるという観点に立ち、フィードバックの収集と統合および対応を行う方法について論じており興味深い。特に近年さまざまなベンダーのドキュメントページに組み込まれている情報収集の仕組みなどの意図がわかって、面白かった。
Chap 9. Measuring documentation quality
ズバリ、ドキュメントの品質を測ることについて書かれた章。本書ではドキュメントの品質を「機能品質」と「構造品質」に分けて評価することを推奨している。その上でさまざまなドキュメントメトリックを列挙している。
なお「SREの探求 ―様々な企業におけるサイトリライアビリティエンジニアリングの導入と実践」に良いことが書いてあるらしい。たぶん「19章 ドキュメント作成業務の改善：エンジニアリングワークフローへのドキュメンテーションの統合」が該当するみたいだけど、まだ読んでないんだよねー
Chap 10. Organizing documentation
増加するドキュメントの整理について、情報アーキテクチャなども考慮して実施することが書かれている。その結果としてサイトナビゲーションの改善やランディングページの整理などを実施するという話。
Chap 11. Maintaining and deprecating documentation
ドキュメントの保守と廃止について。例によってドキュメントもプロダクトの一部と考えるので、メンテナンスの計画を行い実施するという流れになっている。またプロダクトと同様に自動化も考慮する必要があるという話。
Back Matter
補足というか付録。
- 専門家をいつ雇うか
- プロジェクトの文書化に役立つリソース集
膨大なリスト・・・
おっと思ったのは、タフテのこんなビデオが紹介されていたこと（知らなかった）
www.youtube.com
本を読むのがつら過ぎて詰んでたところなので、こんどゆっくり見てみようと思う
