エンジニアのためのドキュメントライティング - 読書メモ
ジャレッド・バーティ（著）、岩瀬 義昌（翻訳）「ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング」を読んだ。原著は「Docs for Developers」。
エンジニアのためのドキュメントライティング 単行本 - Amazon
Docs for Developers: An Engineer’s Field Guide to Technical Writing - Amazon
プロダクトを作成していて、仕様やコンテキストを伝えたい人に適切に伝えたいと思う。しかし、刻々と変わる仕様やコンテキストをどのようにまとめるべきかどのように管理すべきか悩んでいた。ドキュメントについての書籍がないのかなと探そうとしていたところにこの本が出版されようとしており、「これだ！！」と思いすぐに予約した。
とても読みやすくスラスラ読める。そして「ドキュメントライティング」本なだけあって、すごくわかりやすく丁寧にまとめられている。
前提
本書は、一般ユーザーに公開するドキュメント（たとえば、APIドキュメントやサービスのリファレンスなど）のよりよい書き方・管理方法についてまとめられている。
そのため、社内に閉じたドキュメントなどについて言及されてはいない（設計書とか）。しかし、ドキュメントのターゲットが異なるだけで、ほぼ応用が利くと思う。個人的に内部向けのドキュメントをどのように・どれくらい管理すべきかの解決策が知りたかった。十分に応用が利くと感じている。
印象に残った部分
ドキュメント品質「機能品質」と「構造品質」
とても印象に残ったのは、書籍全体にわたって「一貫性、明確、簡潔」さを強調されており一貫していた。一貫性が入っているだけに。実際にエンジニア向けドキュメントを読んでいて、表現が複数あるととても迷う。思い返すと納得がいく。
しかし、「簡潔」は難しい要素だと感じる。これは伝える相手やコンテキストに応じて「簡潔さ」が変わるためだと思う。本書にでてくる「機能品質」を高めていく過程で「構造品質」として磨き込んでいく要素なのだと感じた。
読み手の矛盾
「読み手は情報を探してドキュメントにたどり着く」
「読み手は書いてある内容をほとんど読まない」
引用元ページ:82
特に意識してはないが、確かにとても読み飛ばす。タイトルと見出し、画像やサンプルコードを眺めつつ探している内容っぽいものを見つけるようにドキュメントを探査している。
73ページと78ページに記載されている以下について
ドキュメントのタイトルは、ドキュメントを読むことで達成できるゴールを要約したものにすべき
見出しは道しるべ
引用元ページ:78
「読み手の矛盾」に対して、理にかなった対応になっていると思う。 いかに見つけやすいか、いかに目的を達成できるか。SEO対策にもなり得そう。
ドキュメントのリファクタリングとレビュー
不自然な表現は書き換え、重複情報を削除し、不要な言葉を取り除く
明確さと簡潔さに対する編集は、ドキュメントに対するリファクタリングと考える
エンジニアにささる表現だと思う。また、レビュイー・レビュアーへの配慮として執筆内容に対するフィードバックは、「個人に向けられたものと感じてしまう」問題を取り上げ、以下のように記載があった。
レビューは、コンテンツの改善を目的としたものであり、書き手を個人として避難するものではない事をおぼえておいてください
ドキュメントのレビューは、よりゴールに近づけるように、読み手を助けようとする書き手を助けている
引用元ページ:104
たびたびレビューの仕方が話題になるが、書き手への配慮があって素敵だと思った。
雑なメモ
知識の呪い
他人が自分と同じ知識を持っていると思い込んでいる認知バイアスのこと
引用元ページ:28
コールアウト
ドキュメントのある時点で、知るべきちょっとした情報だが、コンテンツの流れにそぐわない情報に気づくことがある
コールアウトは、ドキュメントの流れを断ち、読み手が回避すべきシナリオの強調に役立つ
引用元ページ:81
Confluenceの情報マクロや、Zennのメッセージがこのコールアウトだと思う。ちゃんと使うべきポイントがあるため、使いどころを間違えないようにしたい。今まで、ビジュアルの使いやすさだけで使っていた気がする。
プラッシング（plussing）
ピクサーで行われているフィードバック方法
「建設的な追加提案ができるなら、アイデアを批判してよい」
引用元ページ:105
エドワード・タフト
最小のスペースで、最小のインクで、最短の時間で、読み手にアイデアを最も多く与えてくれているものことが。最高のグラフィックスです
引用元ページ:127
見た目の悪さによって、読み手はコンテンツへの興味を失うことがある
引用元ページ:129
最初は作り込み過ぎずに、実際に動く、最もシンプルなプロセスからはじめた方がよい。そして、まずはそれを繰り返して使ってみましょう
トイルの存在を理解できなければ、そのトイルを自動化してなくせないから
引用元ページ:155
機能品質がより重要
ゴールを達成していなければそれは不十分なドキュメント
引用元ページ:182
駄文
ゼルダBoW、もうすぐクリアできそう。もっとじっくり探索したいが新作が発売されてしまう。楽しみ。