パルカワ2

最近はFlutterをやっています

ドキュメントのレビューでレビュイーが求めていること

チームで働くとき、様々なレビューがある。ソフトウェアエンジニアとしてはコードレビューを頼むことが一日に何度もあると思うのだが、最近の僕はドキュメントを書くのが大半の仕事になっていて*1、ドキュメントのレビューをプロダクトマネージャーや他のソフトウェアエンジニアにお願いすることが多い。

コードレビューはインターネットに様々な知見が溢れていて、ソフトウェアエンジニア同士で結構脳内同期が出来ていると思う。なのでコードレビューでは雑にレビュアーのアサインをして毎回ここを見てほしいですとかは言ってない。それと同様にドキュメントのレビューでも「レビューお願いします」というだけですべてを任せていたのだけど、そもそも自分がドキュメントをレビューしてもらう時にレビュアーに何を求めているのかなど言語化していないなと思ったので言語化してみようと思う。

前提

  • ここで扱うのは、ドキュメントのレビューである
  • ドキュメント＝他の人に考えを広めるためのものである
  • 考えを広めるためには考えを理解してもらう必要がある
  • ここでは、何を指摘してほしいかを書いている。どう指摘するべきかは書いてない。そのあたりはデザインレビューやコードレビューと同じだと思う。

ドキュメントレビュアーに求めていること

5W1Hの不足の発見

他の人に考えを広めるためには5W1Hが大事になるとおもう。

例えば、Aというものを導入するときに「Aを導入します。Aとは〜です」と書かれただけのドキュメントだと他の人はなぜAを導入するのか理解出来ないし理解できないとやる気も起きないと思う。

読み手が理解するうえで不足している部分だったり意味不明の部分があれば指摘してほしい。例えば、以下がなかったり意味不明な場合は指摘があると嬉しい。

  • このドキュメントの目的
  • 現状整理、現状の課題とは
  • 満たしたいこと、ゴールではないこと
  • Aとはなにか、なぜAか（メリット）
  • Aのデメリット
  • Aをどのように導入していくか、Next Action（誰がいつまでに何をするか）
  • 想定質問
  • まとめ：Aは満たしたいことを満たせるかなど

見落としている視点の発見

ドキュメントを書くというのはドキュメントを書く人間の考えを文字にすることになる。自分の考えなので自分視点になりがちで、他の人の視点が足りていないことがある。

例えば最近僕のドキュメントがレビューされて良い指摘だなと思ったのは、僕はソフトウェアエンジニア視点で「テスト設計書のレビューで、レビュアーは何をレビューしたいのか」だけを書いていたけど「テスト設計のレビューならレビュイーであるテスト設計者がレビュアーに求めている事も重要だよね」みたいな指摘が良いなと思った。

コードレビューやデザインレビューでも同じような気がするが、ドキュメントを書くうえでもそもそも考え忘れていることは人間なのであると思っていて、それらの指摘がもらえると嬉しい。

ドキュメントを読んだ感想

Aというものを導入するためのドキュメントなら自分は理解して取り組めそうだなみたいに思ったらそう書いてもらえると嬉しい。「LGTM」や「よさそう」とかでもいい。

意味がわからない所の発見

日本語って難しいので気を抜くと意味がわからない文章になったりする。プログラム言語は意味がわからないとエラーになるので便利。

誤字脱字は指摘せずに直して良い

誤字脱字はいちいち指摘されて直すのは時間の無駄なので勝手に直しちゃってほしい。

まとめ

意外と少なかった。書いていくと見てほしい部分が増えていくかもしれないが、見落としている視点の発見というのが一番重要な気がする。

*1:昔の自分が今の僕を見たら驚愕するだろうな