ドキュメントを書くたびに「これで伝わるのか」と不安になる、書いたが誰も読んでいない——それはドキュメントの目的と読者の設定が曖昧なことが原因だ。この本でテクニカルライティングの原則を学べば、読まれるドキュメントが書けるようになる。
「書ける」と「伝わる」は別のスキル
エンジニアは文章が書ける。でも、書いたものがユーザーや同僚の問題を解決しているかというと、別の話だ。APIドキュメント・チュートリアル・仕様書・README——どれも書き方が分からなくて手が止まる、あるいは書いたが使われないという経験は多い。
本書『エンジニアのためのドキュメントライティング』は、テクニカルドキュメントを読者の問題解決という視点で設計する方法を体系的に教える。Google出身のエンジニアライターが著した翻訳書だ。
読者を中心に据えたドキュメント設計
本書はドキュメントの種類（チュートリアル・HOW-TO・リファレンス・説明文）をそれぞれ分類し、それぞれの目的・構成・書き方の原則を解説している。読者が誰で、何を知りたいかを明確にしてから書くという発想が、全体を貫いている。
ドキュメントの質が変わった5つの学び
- ドキュメントの種類の使い分け: チュートリアル・HOW-TO・リファレンス・概念説明の4種類の目的と構成の違いが整理でき、用途に応じた書き方ができるようになった
- 読者の視点に立つ技術: ドキュメントを書く前に「読者は誰か」「何を解決したいか」を明確にする習慣が身についた
- 段落ごとの目的設計: 情報を羅列するのではなく、各段落が読者の理解をどう進めるかを意識した構成ができるようになった
- コード例と説明の関係: コードサンプルを単体で置くのではなく、前後の文脈と組み合わせて理解を促す書き方が学べた
- ドキュメントのメンテナンス設計: コードと同じようにドキュメントも保守するための、更新しやすい構造の作り方
書くことが変わると、チームが変わる
良いドキュメントはチームの認知負荷を減らし、オンボーディングを速くし、サポートコストを下げる。本書でテクニカルライティングの基礎を固め、読まれるドキュメントを書く力を身につけてほしい。