2023年3月に出版された「エンジニアのためのドキュメントライティング」を読んだ．原著は Docs for Developers で，翻訳を担当された @iwashi86 さんに本書を送っていただいた．ありがとうございます❗️そして出版おめでとうございます🎉
本書は今まで書いてきたテクニカルドキュメントに対して "できてなかったな〜" という気付きを与えてくれるイイ本でした📖 読みながら感じたことを大きく分類すると以下2点！印象に残ったところを中心にまとめようと思う．
- テクニカルドキュメントの重要さを改めて認識できた👌
- テクニカルライティングという仕事（ポジション）に興味を持った👀
目次
- PART I「ドキュメント作成の準備」
- CHAPTER 1 : 読み手の理解
- CHAPTER 2 : ドキュメントの計画
- PART Ⅱ「ドキュメントの作成」
- CHAPTER 3 : ドキュメントのドラフト
- CHAPTER 4 : ドキュメントの編集
- CHAPTER 5 : サンプルコードの組み込み
- CHAPTER 6 : ビジュアルコンテンツの追加
- PART Ⅲ「ドキュメントの公開と運用」
- CHAPTER 7 : ドキュメントの公開
- CHAPTER 8 : フィードバックの収集と組み込み
- CHAPTER 9 : ドキュメントの品質測定
- CHAPTER 10 : ドキュメントの構成
- CHAPTER 11 : ドキュメントの保守と非推奨化
テクニカルドキュメントをプロダクト開発のように考える
本書を読んで印象に残ったのは，ドキュメントも「プロダクト開発のように考えている」というところ．ドキュメントの読み手（ペルソナ・目的）を整理して，ドキュメントをうまく構造化してまとめて，評価やフィードバックを基に改善を繰り返す．まさにプロダクト開発のフローのように感じられたし，同時にそれほど注力するべきとも言える❗️ドキュメントライティングをある意味 "おまけのように" 考えてしまうと，価値がなく誰にも読まれないドキュメントになってしまう可能性もある．
CHAPTER 1 で解説されている「読み手の理解」は良かった👏 ドキュメントの読み手を意識してドキュメントを書くべきということは頭では理解していても案外できていないこともありそう．結果的に "独りよがりな" ドキュメントを書いてしまうことにも繋がる．そして，ドキュメントを読んでもうまく使えなかったときの状況をまとめる「フリクションログ」というテクニックも参考になった．
知識の呪い
人間は他人が自分と同じ知識を持っていると思い込んでいる という認知バイアスを「知識の呪い」として紹介されていたのも良かった．僕自身は技術講師（テクニカルトレーナー）として働いているため，技術を教える立場としてこの「知識の呪い」には絶対に該当しないように常に気を付けているけど，ドキュメントライティングでも意識するべきだと気付けた．
テクニカルドキュメントの種類
CHAPTER 2 でテクニカルドキュメントの種類（コンテンツタイプ）が以下のようにまとまっていて，分類として参考になった．ここまで厳密に分類されてドキュメントが公開されている事例ってどのぐらいあるんだろう．また "コンセプトドキュメントや手順書" は「教育や情報提供」を取り扱って，"リファレンスドキュメント" は「原因と結果」を取り扱うという解説があって，ここでも読み手を意識した分類になっているんだなぁーと感じた．
- コードコメント
- README
- スタートガイド (Getting Started)
- コンセプトドキュメント
- 手順書
- チュートリアル (Tutorial)
- ハウツーガイド (How To Guide)
- リファレンスドキュメント
- API リファレンス
- 用語集
- トラブルシューティングドキュメント
- 変更に関するドキュメント (Change Log)
そして，僕は気になるサービスやツールを試すときに「チュートリアル」を試してテックブログにまとめることが多く，チュートリアルの良し悪しによってそのサービスやツールへの第一印象が決まってしまう．実際にこういう体験があるからこそ，テクニカルドキュメントの重要性も改めて認識できた．また本書では Getting Started / Tutorial / How To Guide それぞれの違いがまとまっていたのも良かった．Getting Started = Tutorial というドキュメントも結構ある気がする...
非推奨化 (deprecated)
ドキュメントは1度書いて終わりではなく継続的にメンテナンスをしていく必要がある．メンテナンス計画を考えたり，ドキュメントオーナーを任命するなど，CHAPTER 11 で解説されている内容は特に良かった．またメンテナンス作業をできる限り自動化するというプラクティスも参考になった．
- 鮮度確認（最終更新日を表示する）
- リンクチェッカー（リンク切れを回避する）
- ドキュメントリンター（文章チェックをする）
- リファレンスドキュメント生成（OpenAPI / Swagger などを活用した自動化）
ドキュメントリンターとして textlint は便利だし，textlint-rule-no-dead-link を使えば textlint でリンク切れも検知できる．
そして，不要になったドキュメントを突然消すのではなく，非推奨化 (deprecated) という形で事前に読み手に伝えるというプラクティスも実体験としてあると嬉しく，明確にまとまっていて良かった．実は CHAPTER 11 を読んでいて "書いてあったら引用しやすくて嬉しいなぁー" と思っていたことがあって，それは「ドキュメントを削除するときに最低限リダイレクト設定はして欲しい」という話なんだけど，最後の "まとめ" に ユーザーが立ち往生しなくて済むようにリダイレクトを設定してください。 と書いてあって「最高〜」と心の中で叫んだｗ
テックブログに当てはめて考える
本書で取り扱う "テクニカルドキュメント" として，テックブログは当てはまらないところもあるとは思うけど，テックブロガーとして参考になるプラクティスもあった．例えば，CHAPTER 5 で解説されているサンプルコードのプラクティスや CHAPTER 6 で解説されている図解の必要性（百聞は一見にしかず）など❗️
さらに CHAPTER 3 で解説されていた「流し読みに適した書き方」というのは重要なマインドセットだと思った．テックブログを書いてる側としてはうまく推敲した文章全てを上から下まで読んでもらいたいとは思うけど，実際には "知りたいことを最速で見つけたい" というニーズも多いはずで，期待した通りに読まれないことを受け入れる必要がある．TL;DR を活用したり，文章を簡潔にまとめたり，図解を活用したり，今後工夫できることはたくさんあるな〜と気付けた💡
＼( 'ω')／ 流し読み時代を受け入れよう！
付録 B（リソース）と付録 C（参考文献）
本書では関連するウェブサイトや論文など，多くの引用元が注釈されていて，さらに本書の最後には付録としてまとまっていた．付録は非常にありがたく，はじめて出会えたものもあれば，読もう読もうと思って後回しにしていたものもあって，優先順位を上げるきっかけになった❗️
Google 提供の Technical Writing Courses は前から気になっていたけどまだ受講できてなく，やるぞー！という気持ちになった．本書には2コースと書かれていたけど，現在は4コースありそう．
- Technical Writing One
- Technical Writing Two
- Tech Writing for Accessibility
- Writing Helpful Error Messages
REST API のドキュメント開発を学べるコース💡内容的には非常に深く気になるけど，162ページもあってボリュームすげぇーｗ
- I: Introduction to REST APIs
- II: Using an API like a developer
- III: Documenting API endpoints
- IV: OpenAPI spec and generated reference docs
- V: Step-by-step OpenAPI code tutorial
- VI: Testing API docs
- VII: Conceptual topics in API docs
- VIII: Code tutorials
- IX: The writing process
- X: Publishing API docs
- XI: Thriving in the API doc space
- XII: Native library APIs
- XIII: Processes and methodology
- XIV: Metrics and measurement
- XV: Additional resources
ソフトウェアアーキテクチャをうまく表現するための C4 model (context, containers, components, code) も理解しておこう．
その他メモ
- エラーをドキュメントに載せるときは検索しやすいように1ページにまとめる
- コールアウト
完璧主義から脱却する（書籍 "完璧を求める心理" とも関係しそう）- プラッシング (Plussing)
- サンプルコードを動かすサンドボックス環境があると便利だけど多くの場合は過剰
- テクニカルライターの多くはメンテナンスの面から映像には慎重
- TTHW (Time to Hello World)
あわせて読みたい・聞きたい
本書のポイントや本書とあわせて読むと良さそうな名著「理科系の作文技術」などの紹介もあって非常にうまくまとめられていた．実は本書を読みながら，対象としているテクニカルドキュメントの具体的なイメージが掴めず，数回戻って読み直したりしていた．最終的に SaaS / OSS ドキュメント・API ドキュメント・GitHub の README.md などを想像しながら読むことにしたけど，社内ドキュメントはどうなんだろう〜？という点は疑問だった．以下のスライドの P.50-51 でちゃんと 実際にはほとんどのドキュメントで応用可能 とフォローアップされていた❗️
原著の共著者 Zachary Sarah Corleissen にインタビューする fukabori.fm のエピソードも良かった📻
まとめ
2023年3月に出版された「エンジニアのためのドキュメントライティング」を読んだ．重要なのは本書で学んだプラクティスを実践して，ドキュメントによって読み手を支援できるかどうかだと思う．できそうなところから着手していこう．また今まで長年テックブログを書き続けているけど，この経験を役立てられそうなテクニカルライティングという仕事（ポジション）にも興味を持った💡
テクニカルドキュメントの重要さを改めて認識できるイイ本でした❗️おすすめ❗️
誤植など
既に報告されているかもしれないけど 初版第一刷 を読んでいて気付いたところをまとめておくー👾
- P.42
表してします。→表しています。 - P.54
コンセプトガイド→コンセプトドキュメント（もしかしたら表記揺れ？） - P.59
熱心の→熱心な - P.84
アップロート→アップロード - P.211
Kubenetes→Kubernetes - P.222
付録 2→付録 B - P.228
https://snagit.com/→https://www.techsmith.com/screen-capture.html（リダイレクトされる？）
