感想とか個人的に良かった内容のメモなど。
ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング - Amazon.co.jpChapter1 読み手の理解
ユーザー理解が大事という話。これはプロダクト開発一般にも言える話で、BABOKとかの話でも出てくるやつだと思う。
顧客のニーズや顧客のレベルに合わせたドキュメントを作らないと価値が無い的なやつ。
Chapter2 ドキュメントの計画
どんな種類のドキュメントを作るとよいか考えましょうというやつ。
コンセプトガイドなのか、ハウツーなのか、用語集なのか。
それぞれのドキュメントの特性を紹介してどういう目的が達成できるかを知り計画しようという感じ。
Chapter3 ドキュメントのドラフト
ドキュメントを書き始める難しさの話がメイン。
ツールとかは一応説明してるけど、ここではそれ自体が重要という話ではない。
一番大事なのは、「読み手の期待に答える」で書かれているようなことを意識して書く/書けること。
- 情報を流れを考える
- タイトルに書いたゴールを読み手が達成するために、読み手が知っておくべきこと、やるべきことを考える
- 正しいタイミングで、正しい情報を読み手に提供できるようにする
- 必要であれば、読み手がより有益なことに集中できるよう手順を並び替える
- 見出しをつくるときの注意点
- 読み手が見出しをさっと読めば、ドキュメントの内容を大まかに理解できるようにする
- 一貫性を保つ、あるタスクを完了させるための手順書であるならば、見出しをすべて動詞で終わらせるなど
- リストを作るときの注意点
- 読み手に最も役立つ並べ方を考える
- リストの項目が10個以上になってきたら、小さいリストへの分割を検討
- コールアウトを使うときの注意点
- あまりにも多いと読み手が疲れてしまうかもしれないので、読み手が見逃すべきでない重要な情報にのみ、コールアウトを使う
あとは、「読み手は書いてある内容をほとんど読まない」 というのが大事。
実際に読み手が1ページに費やした時間を基に考えると、読まれている単語数は1ページで多くて28%程度みたいな話。
これは実際自分が本とかドキュメントを読むときの感覚とも近く、全部の文章を一言一句逃さずに読まないと何を書いているのか理解できないドキュメントとかを渡されると「ウッ…」ってなるのはこれ。
見出しやコールアウトなどを見ながら、適宜気になる部分だけ読んで内容を把握し、詳細な議論や疑問があるときに周辺をしっかり読むという読み方が多いと思う。
なので、分量で圧倒してしまうと、議論が必要な重要な設計考慮漏れなどが隠れてしまう。
「流し読みできるようなドキュメントを書くことを心がけると良い」いわれてもピンとこないと思うので、とりあえずここまで話してるようなテクニックを使って書いてみればいいと思う。
どうしても量が多くなるなら、それは1つのドキュメントにまとめるべきでない可能性があるので分割を検討するとよい。
最後には、簡潔なドキュメントをどうやって書けばいいのか行き詰まったときにやるとよいことが紹介されていた。
基本的に同意という感じで特に自分がよくやってるのは、以下の3つ
- 文法について心配するのを止めて、考えをまず書き出す事に集中する
- 読み手に情報をすべて伝えることが目的であって、完璧なドキュメントを作ることが目的ではない
- 知っていることを書いている最中に、何かが足りないことに気づき、それを調べて、行き詰まりが解消したりもする
- ドキュメントの冒頭から書き始めない
- 書けるなら書いてもいいけど、自分は大体最後に見直して直すことになるで、書きやすいところから書き始めればよい
- 考えを紙や付箋などに書き起こしてみる
- 点を点を線でつなげたり、グルーピングしたりしてるとなんか見えてきたりして行き詰まりが解消したりする
- 「Chapter6 ビジュアルコンテンツ」でも出てくるがとりあえずホワイトボードとか紙とかになんか書いてたら情報が整理されたりする
Chapter4 ドキュメントの編集
編集つまり、レビューの話。 セルフレビューもだが他人にレビューしてもらう話もしている。
なぜレビューが必要か。
文法や読みやすさだけではなく、できるだけ明確に、早く、
役立つ方法でユーザーに情報を伝えられるようになる。
レビュー時には、改善したいドキュメントの要素の1つに集中するのが有効。 一度にたくさんの要素に集中しようとすると、扱う対象が多すぎて、進行が遅くなる。
一連の複数の周回に分解して、1つの周回で1つの編集観点に絞ったほうがより編集が早くなる。
以下など観点で周回
- ドキュメントに書かれている技術情報がすべて正確か？
- ドキュメントの構成はこれでよいか？
- ドキュメントを開いて最初に読まれるのは、タイトル・見出し・目次
- これらの最初の言葉がドキュメントの中で最も重要な部分であり、読み手の望む情報への経路を示す道標を提供している
- 完全性
- 読み手にすべての情報を伝えることではない
- 情報が足りなさすぎると同時に、多すぎると読み手が離脱しやすくなる
セルフレビュー
- 自分が書いたドキュメントを自分ですぐにレビューすると、ある程度の日を置いてから新鮮な気持ちでレビューするときほど、効果的にならない
- 編集用チェックリストを利用するのが有効
チェックリストの例
* タイトルが短くて具体的である
* 見出しは論理的に並べられており、一貫性がある
* ドキュメントの目的が最初の段落で説明されている
* 手順はテストされていて動作する
* 技術的なコンセプトが説明されている、もしくはリンクされている
* テンプレートの構成に従っている
* リンクがすべて有効である
* 誤字脱字・文法チェックツールが実行されている
* グラフィックスや画像が明確で有効である
* 前提条件や次のステップが定義されている
レビュー依頼するときはフィードバックの種類を伝えるのも有効っぽい。これは実際にこの本を読んだ後にやってみたら良かったという声を聞いた。
* 構成をレビューしてほしいのか？
* 技術面なのか？
* 明確さと簡潔さを見てほしいのか？
* etc...
Chapter5 サンプルコードの組み込み
わかりやすい、使いやすいとかを気をつけようといった内容。
省略記号とかも使って簡潔にしようなどなど。
Chapter6 ビジュアルコンテンツの追加
図とか使っていこうという話。
1枚の画像は、文章に比べて少ない認知処理で、複数のことがらを関連づけることを助けてくれ、
文章よりはるかにすばやく対象の理解を深められます。
効果的ではないビジュアルコンテンツは、情報の伝達を妨げます。
これは通常、次の点が欠けているため
* 理解容易性
* アクセシビリティ
* パフォーマンス
とはいえ図とか作るの難しいよね〜というのはある。
ドキュメントと同様に、効果的な図の作成は良い計画から始まります。
簡単な図を描くために、ホワイトボードや紙とペンを用意しましょう。
自分は、iPadとかにApple Pencilでガーッと書き始める事が多い。
特に登場人物（DB,API, ユーザー, 運用する人, Batch, etc…）を出し切って関連を線とかで表現していくのが重要だと思ってる。 そこから削っていったり、分割してより詳細化したりといった流れになる。
欧米人であれば、左から右に、上から下へ読み進める傾向があるらしい、かなり図のみやすさが変わるのでこれも重要。
色に一貫性をもたせるとか、ラベルを利用するとかも大事。 ただし要素が増えすぎるわけわからなくなるので、凡例を用意したりするのも忘れないように。
文章はすぐに時代遅れになりますが、画像はさらに早く時代遅れになります。
ユーザーインターフェース（UI）を1つでも変更すれば、スクリーンショットは古いものになります。
これはマジでそうで、図中に注釈で詳細なことを書きすぎると、ちょっとAPIのendpoint名を変えたりしたら図がもう古くなってしまうので、理解を助けるようにしつつ、ふわっとさせておくのも大事だと思う。
Chapter7〜11
ドキュメントの公開、フィードバック収集や運用保守に関する話がメイン。
今回、自分は社内でのdesign doc執筆に役立ちそうな情報を求めて本書を手にとったので、この章の内容は軽く流して読んだので「ほほーん」くらいの感想である。
ただ、品質の話で「簡潔な」のところに書いてあった、これはとても良かったので紹介しておく。
読み手の理解を妨げるものはすべて取り除き、
関連はしているもののすぐに必要でないものはリンクを張っておきましょう。
「図に不要な線は含めてはいけないように、また機械に不要な部品を入れてはいけないのと同じ理由で、
1つの文に不要な言葉は含めてはいけませんし、段落に不要な文章を含めてはいけません」
あとは、ドキュメントの責任は全員にあるというのはそうだが、逆に誰も責任を持ってないとも言えるため、実際は誰かがオーナーになったほうが良いといった内容も記載されてた。
メンテしない書き捨てのドキュメントみたいなのもあるが、そうでない場合はメンテの方針と責任を明確にするとドキュメントが古くなることを防止するのに役立つというのはまさにそうだなぁと思う。