頭の中にスタックが3つしかないからネストは3つまでがいいし。リンクを辿って色んなところに飛ぶと戻ってこれないし。こういう意味にも取れるけどどっちだろう？とかなるし。似たようなことが複数の箇所に書いてあると目diffをしてしまうし。気が散りやすいし。
自分にとって読みやすいドキュメントを書く
だから、書くときは「自分が頑張らなくても読めるように」と思って書く。そしたら、他の人にとっても読みやすいんじゃないかと思って。
そんな風にして最近書いたドキュメントを褒めてもらって喜んだので、こんなこと気にしながら書いてるかなーと思うのをメモ。ふわっとした話。
誰にどうなって欲しいか？
具体的に誰か一人を想像する。「全員にとって」ではなく「その人にとって」価値のあるドキュメントにする。
- 彼は、どうしてこのドキュメントを見たいと思ったのか？何に困っているのか？
- 彼は、今どんなことを知ってるのか？
- 彼は、このドキュメントを読むことで、次にどんなアクションを起こすことができるようになるか？
みたいな。「何を書くか」より「それによってどうなって欲しいか」を考える。プロダクトも、プレゼンも似てるとこあるよね。
Agile 2011 Conference : ジェフ・パットン氏によるアジャイルな要件定義手法「ユーザーストーリーマップ」のチュートリアル - kawaguti’s diary
言葉の定義
ひとつのものを色んな呼び方で呼ぶとつらいし、ひとつの言葉で複数のものを指すのもつらい。結局どれを指してるんだろう？ってのを文脈から想像しないといけないし、そもそも違うものを想像してしまったりしてしまうから。
ので、紛らわしいものは、言葉の定義を作る。「このドキュメントでは、こう呼ぶ」で構わないかな。全部細かく定義してあったら読みたくなくなるから、紛らわしいものだけ。
最初から書くときもあるけど、どっちかというとドキュメントを書きながら「あれ？この言葉さっき違うものを指すのに使ったなぁ・・・」ってなることが多くて。そういうときはちゃんと名前を与えてあげると色々発見できてスッキリする時ある。
ユビキタス言語 な雰囲気するね。
ぱっと見て分かりたい
ぱっと見：図を使う
図とかを使って、最初に全体の概要をぱっと見て「なるほど？」って言えるようにしたい。んで、図は、そのぱっと見の印象が正しい理解になるように書く。たまに、ぱっと見た印象と実際が違うドキュメントがあったりして、そういうの混乱するから。
ぱっと見：概要から詳細
最初から詳細を書くんじゃなくて、概要があって、全体像を頭の中に描けた後に、詳細が書いてあるのがいい。
ぱっと見：全部は要らない
書いてるときの自分の頭だと、その対象を深く理解してることが多いので、全部正確に書きたくなってしまうんだけど、「誰にどうなって欲しいか？」という目的に対して必要な最低限の情報を軸にする。
読まれる時間の方が多い
結構頑張って書いて書き終わったら(ヽ´ω`)するし、もういいじゃんって気持ちになるんだけど。一晩寝かせてみて、もっかい見てみる。んで、読みにくい部分があれば直すし、不要だなと思う部分があれば、頑張って書いたやつでも削除する。
よく、コードは「書くよりも、読まれることの方が多いから読みやすいコードを書こう」って言われるけど、それってドキュメントもそうだなーって思いながら。
