Twitterで話題になっていたので読んでみました。
（僕の知る限りでは）どんな開発現場であっても、ドキュメントは存在します。開発するうえで、ドキュメントを全く必要としない現場というものはありませんでした。ということは、ドキュメントも機能の一部です。
しかし、「ドキュメントが足りない」という声はなくなりません。ではなぜ足りないのか。それは、「書き方を知らないから」。
、、、というような書き出しで始まり、ドキュメントの重要性から実際にどう書くのかを、教えてくれる本です。
僕自身、メンバーのドキュメントレビューをする機会が増え、勉強のためにこれまでライティング系の本は10冊近く読んできました。 個人的には割とよく見るなという内容で若干面白みに欠けるところはありましたが、中身はエンジニアであれば確実に押さえておきたいレベルの内容でした。
新卒や若手向けの推奨書籍としてもよさそうだなーと思いました。
個人的に新たな発見だったのは、「ドキュメントの編集」の章で、「編集はいくつかのプロセスに分けて行うとよい」というものです。
以下の順番で見ると、ユーザーの求める情報に徐々に近づくそう。
- 技術的な正確さ
- 完全性
- 構成
- 明確さと簡潔さ
それぞれの項目が何を指しているかというよりは、「一気に全部見るのではなく、観点を分解して重要な観点からいくつかのステップに分けるとよい」というのが学びでした。
コードレビューにおいても全く同じことが応用できそうです。直近、「コードレビューどこまで細かくみる問題」などをメンバーと話す機会がありました。その時「必ず直してほしいところ」「できれば直してほしいところ」「好みにも近い、妥協できるところ」という大きく3つの階層で見てるよーという方がいて、何事も分解だなーと思ったのと近い話でした。
よいドキュメントを書いて、よりより開発体験を提供できるチームにしていきたいです。
以下読書メモ
## はじめに
- 開発時に必ず必要になるのであれば、ドキュメントも機能の一部
- それなのになぜこれほどまでに足りないのか
- 「書き方を知らない」から
## 読み手の理解
- 知識の呪い
- 自分と同じことを相手も知っているだろうという認知バイアス
- なぜドキュメントを書く必要があるのか？
- ユーザーに何らかのタスクを完了してもらいたい、もしくは何らかの方法で行動を変えて欲しいから
- ユーザーにとっての技術的なゴールと、ユーザーにたどり着いて欲しいというビジネス的なゴールがある
- ユーザーが誰であってドキュメントに求めるものはなにか、という仮説検証をする最も簡単な方法は、ユーザーとの直接対話
## ドキュメントの計画
- コードコメント
- 「コードの自己文書化」は滅多にない。複雑な処理コードの前にある1行のコメントが読み手の理解する時間を大幅に減らす
- ハウツー
- ドキュメントの途中にあるリンクは、読み手に読む必要があると思わせてしまい、注意を逸らしてしまう
- 最下部にある追加のセクションに記載する
## ドキュメントのドラフト
- タイトルから始める
- タイトルはドキュメントのようやく
- ブログはタイトル最後がいいけど、逆
- 最初のドラフト完成のチェックリスト
- 大見出しはドキュメントのゴールを要約しているか
- 複数の見出しによってドキュメントは十分に要約されているか
- ドラフトは最初から最後まで読み手のニーズに応えたか
- 情報の流れは読み手にとって理解しやすいものか
- フリクションログで見つけた課題は解決されているか
- 何らかのドキュメントパターンやテンプレートに正しくしたがっているか
- 全手順が動作することをテストし確かめたか？
## ドキュメントの編集
編集はいくつかのプロセスに分けるとやりやすい。以下の順番でみると徐々にユーザーの求めるものに近づける
- 技術的な正確さ
- 完全性
- 構成
- 明確さと簡潔さ
## サンプルコードの埋め込み
- どんなきれいな言葉より、エンジニアはサンプルコードを見たがっている
- できればコピペで動いてほしいと思っている
## ドキュメントの品質
- ドキュメントが優れているのは目的にかなっている場合である
- 機能品質：ドキュメントの目的やゴールが達成されているかどうか
- 構造品質：ドキュメント自体がうまく書かれているか、うまく構成されているか
### 機能品質
- 測定は困難
- 以下の要素がある
- アクセシビリティがあること
- 目的があること
- 見つけやすいこと
- 正確であること
- 完全であること
### 機能品質と構造品質の関係性
- 機能品質なくして全体的な品質はない
- 構造だけよくてもだめ
- 構造が悪くても、機能がよければ最低限OK
