レビューについて
ドキュメントを書いたらレビューをしよう。
書いたドキュメントをより良くするためには何をすべきかというと、やはりレビューをする/してもらうことだと思います。
ドキュメントはレビューをすることでより良いドキュメントになります。 単純な誤字脱字のチェックはもちろん、内容に誤りがあったり、読みやすくなったりします。
そのため、レビューは必要です。
- 事前準備
- 心構え
- どうやるか
準備しておくこと
ガイドラインを準備しよう
- このガイドに沿って作っていることを共有する必要があります
- レビューのルールを作成
レビューしてもらう体制を作ろう
- まずは体制作りが必要です。
- 突然レビューを依頼しても、何を、どんな視点で、どんな背景があって、など、文脈がわからないと難しいものです
- レビューの前に、その点を共有しておきましょう
心がけること
レビューを受けると、たくさんの指摘を受けます。 より良いドキュメントのためには必要とは言いつつも、指摘を受けるのは苦手という方も多いと思います。（私もそうでした）
ネガティブになることもあります。
恥ずかしい間違いをしてしまった...><
どっちでも良いのでは...？
その指摘わかるけど、ここで書くと違うから書いていないんだよな。。。
レビューをしてもらう場合
- はじめから完璧なドキュメントなどないので、指摘は必ず入る
- 完璧を求めず、スピードを求める
- まず、指摘してドキュメントが直ることを良いことと捉える
- 指摘は全て直すくらいの気持ちを持つ
レビューをする場合
- レビュイーの背景を理解する
- 思ったことは遠慮なく伝える
- 声に出して読んでみる
レビューのやり方
レビューは実際にどのようにしていくのか。
レビューをしてもらう場合
- セルフレビューをしておく
- なるべく誤字脱字系は自分で対応しておきたい
- なぜこの文章にしたかの背景もコメントで書く
- あえて消した内容があれば、補足する
- 迷っている点があれば、その旨も書く
- レビューしてもらえることの感謝を伝える
レビューをする場合
- まずは全部読む
- 途中途中で指摘したくなるが、一旦全部読んでみる
参考図書
- 伝わるWebライティング -スタイルと目的をもって共感をあつめる文章を書く方法
- Chapter 11 ライティングを見直そう
- リーダブルコード