自分たちでサービスの開発と運用をしているチームで、僕がどんなことを考えながらドキュメントを残してるかなぁってのをメモ。
## 結論から
来月の自分が読んで分かりやすいなと思えるドキュメントを残す。
## タスクをやってる最中は雑にメモ
タスクをやってる最中は雑にメモを残していく。体裁は気にしないでとにかく気軽に気づいたことや学んだこと、これは来月の自分に残しておきたいなってことをメモしていく。統一感も何もない。
ここで大切にしたいのは
- 情報を残すこと
- 時間をかけないこと
避けたいのは
- きれいにかくこと
- きれいに書かなきゃと思って、内容じゃなくて見た目に時間を取られること
- 書くの面倒だから、あとにしようってしてしまうこと
ということで、走り書きの雑なメモができあがる。でも大切なことは全部書いてある。
## 次はまとめる
タスクがひとくぎりついたら、メモを見ながらまとめる。
ここで考えるのは、書く人の気持ちじゃなくて、読む人の目線。僕は、来月の自分のことを考えながら書く
- 忘れっぽくて、今やったことも明日には忘れてるし
- ドキュメントを読むのが苦手なので分かりやすく書いてないと頭から煙がでる
から、自分を想像しながら書けばいいので便利。
ポイントは
- どういう立場の人に向けたドキュメントなのかを意識する
- エンジニアが新機能を開発するときに見るのか、運用するときに見るのか
- 新しく入ってきた人が見るためのものなのか
- システムの管理者用なのか、利用者用なのか
- とかで書きたい内容が変わってくる
- 全ての詳細をずっと同じレベルで書くのではなくて、段階を経て伝えたいことに届くようにする
- 全体像→中くらい→詳細
- 複雑なものは図をひと目見たら伝わるようにする
- だけど、これも全ての詳細を図に盛り込むんじゃなくて、伝えたいことに焦点を絞った図。
- １ページが長くなりすぎないようにする。
- 読んでるうちによく分からなくなるから。
- かといってページ数が多くなりすぎないようにする。
- 読む気がしないから。
- それから、ページの階層が深くなりすぎないようにする。
- どこまであるんや、って迷子になるから。
## それから削除する
まとめ終わって要らなくなったメモや、重複する部分は削除する。削除は後になればなるほど「消しても大丈夫なのかな？」ってのが分からなくて難しくなる。
コンフルエンスを使ってるので、削除したページはゴミ箱に入るから、やっぱ必要だったわってなっても戻せる。安心。
## 過程が重要な場合
情報を残すときに、最後の結果よりも、過程が重要な場合がある。
そういうときは、結果だけじゃなくて、その過程をドキュメントとして残すことが大切。
## まとめ
ということで、ドキュメントを書くときは
- 「書き出す」と「まとめる」を分ける
- 書く人の気持じゃなくて、読む人のことを考えて書く
- 重複する情報は削除する
- 過程が重要な場合は、結果だけじゃなくて過程もドキュメントとして残す
って感じか。
## あれ？
これ、コードと一緒だ。
- まずは動くようにしてから、リファクタリング
- 読む人のことを考えて書く
- 重複は削除
- コードにあらわれてこない部分をコメントに残しておく
ドキュメントのことを考えてると思ったら、コードのことを考えてた。
