ドキュメントレビューに対する経験知（レビューを語る夕べのイベントレポート）

# はじめに
「[レビューを語る夕べ(2018/06/29)](https://kataruyube.connpass.com/event/90183/)」のイベントレポートです。
（参考：主催者様による[議事メモ](https://scrapbox.io/kataruyube/%E3%83%AC%E3%83%93%E3%83%A5%E3%83%BC%E3%82%92%E8%AA%9E%E3%82%8B%E5%A4%95%E3%81%B9%E3%80%806%2F29)）

補足ですが、学術的な方法論というよりは、各自の経験知を共有し合うイベントでしたので、「レビューの正解」を記載している訳ではないです。
「イベントの参加者には、こういうレビューをしている人が居た」っていう情報を寄せ集めてまとめた感じの記事になります。


# イベント概要
1. ちょっとした設計書を、各自でレビュー（30分ほど）
2. 近くの人同士で、以下を語り合う（15分くらいだったかな？）
    - どういう観点でレビューしたのか？
    - そこに着目したのはなぜか？
3. 全員で語り合う（主催者様によるファシリテーションあり）（2時間くらい）
    - 引っかかった部分はどこか？なぜそこが引っかかったのか？を語り合う時間
    - 上述の議事メモはこの部分。
    - 2時間でも足りないくらい白熱。


# レビュー観点

以下表は、あくまでも粒度の大きさ順。

|seq|大分類|小分類|問い|回答例|
|---:|:---|:---|:---|:---|
|1|目的理解|ビジネス|ビジネス上、実現したことは何か？課題は何か？|交通取り締まりに関するスキルの均一化|
|2||システム|このシステムが、実現したことは何か？解決する課題は何か？（具体的に）|現場利用する減点算出用携帯機向けのアプリケーション開発|
|3||ドキュメント|前行程と後工程との関係性から見たこのドキュメントが定義すべき範囲は何か？|外部設計|
|4||目次・概要|目次レベルで、各項で述べたい内容と関連性はどうなっているのか？|文章が表現する範囲は・・・、表が表現する範囲は・・・。|
|5|整合性|ビジネス|実業務が回るのか？|警察官の手袋を付けていても使える様な端末のため、問題ない。/ネットワークが繋がっていない場合、あとでサーバー送信されるように、溜めておく仕組みがある。|
|6||システム|アーキテクチャーに適合しているのか？|-|
|7|||検証可能か？|-|
|8||ドキュメント|ページ間、項目間で整合性誤りはないか？|-|
|9|||誤字脱字はないか？|-|

いろんな人がいろんな表現で話をして居たが、個人的にまとめると上記な感じになる気がした。
見る順番/指摘する順番としては、上から順の人が多く。
気づく順で言えば、「誤字脱字」が最初に気になる人が多い感じだった。


# レビュー技法
## ドキュメントの読み方
**逐次型**
頭から順に読んで行って、不自然な部分に立ち入ると読むのが遅くなる・・・と行った感じのタイプ。

**俯瞰型**
気になる部分を狙い撃ちでターゲットするタイプ。（天才肌？経験則？）
見て3秒以内に指摘出しちゃう感じ。

**自分は？**
自分は、逐次型っすね。俯瞰ほど天才肌にはなりきれてない感ある。
ただ、文頭から細かく読み進めるのではなく、以下な感じで見ていく。（ハイブリッド？）

1. ざっと全体を見る（目的理解）
2. 2〜3行の文章と、図表を見る（目的理解）
3. 長い文章を読む（整合性確認）
3. 項目間の整合性を見る（整合性確認）

「3. 長い文章を読む」以降は、「1. ざっと全体を見る」「2. 2〜3行の文章と、図表を見る」をクリアした時だけ行う。


## ボトムアップ/トップダウン具体化
上記レビュー観点の中で、脳内検証を行うにあたり、2種類の思考法がある。
（他にもあるようだったが、時間切れで話題にはできなかった。）

**ボトムアップ具体化**
特定の対象を1つ取り上げ、その周りの状況をブレスト的に出していく。
状況は、想像を進めるほど複雑になり、当初予見していなかった問題点をあらわにする事も多い。
この手法は個人の経験値に寄って得られるものが異なる。
新人だから不得意、ベテランだから得意とは限らず、その人固有の経験から指摘が出てくるのがポイント。
ただ、比較的ベテランの方が上手なことが多そう。

テストケースの具体化などのタイミングだと、思考が発散しすぎて非効率的だったり、「今更そこまで立ち戻ります？」的な話になったりしそう。
立ち戻るべきなら立ち戻るべきですが、すでに考慮済みの内容を再度考慮し直すような作業が発生し得えそう。
要件定義や方式設計/外部設計くらいまでが適用範囲といった感じ。

**トップダウン具体化**
すでに分かっている状況をプロパティとして定義し、状況を固定化する。
その上で、プロパティ値を変動させて、状況の変化を検証する。
プロパティの変動に伴う状況を正確に推察するにはスキルがいるため、ベテランになるにつれて得意になると思われる。
厳密な検証は実際のテストで行うものなので、あくまでも脳内検証のレベル。

逆に、想定したプロパティ以上の課題は見つかりにくいため、要件定義等の時にこの考え方をしてしまうと、容易に要件定義漏れが発生する。
テストケースの具体化等には無類の強さを発揮しそう。


## キーワード検知
特定の人は「この部分が光って見える！」などの共感覚的表現をするもの。
自分は、テキスト文書の検索よろしく「すっと目が行く」くらいの感覚で、光るとかそういう共感覚的なものはない。

例
> 75歳以上で運転免許書を自主返納した場合、〜区役所でなにか支援があるのですか？

上記の例だと、「免許書」の「書」が、「光る」「エンボス加工よろしく浮き出る」「太字になる」「フォントが違う」などで見つけられる人が居た。[^1]

[^1]: 正しくは「免許証」

他にも、「数字はつい目がいく」「"ただし"とか"基本的に"っていうワードには注意する」など、がペア内では話題になった。
そのキーワードが起因で問題になった経験があるため、そのキーワードについては、特別に注意が行っているのではないか？と勝手に推測している。

なので、経験が多い人ほど、目につく単語が多いのではないか？
例えば、上述の例だと、「よくある誤字」として、脳内にこびりついている感じ？

注意している語句、よくする指摘を、共有知識化したら面白そう。


## 図表の一貫性
ミスリーディングをさせやすい図表の作り方になっていないか？
例：表のソート順が、大半が「刑罰の厳しい順」に対して、一部だけ「刑罰が軽い順」のものがあった。


## レビューリジェクト
### 疑問点/問題点のストック/カウント
疑問点/問題点を脳内にストックしておく。
ドキュメントの後半で解消されるケースもあるため、気付いた時にすぐに指摘するのではなく、脳内にストックしておく技術。

誤字系はこれをやっている人が多そう。
「一定数以上、誤字を見つけた場合、レビューに値しないとして、セルフレビューからやり直し」って話も出た。


### レビュー粒度
自分は、上記レビュー観点の目的理解（4）までで止めていて、あとは会話しようって感じでレビューしたため、15分くらいで終わってた。
（というか、目的理解のところで相当数の指摘が出てきたため、「整合性の評価には値しない」と判断して、レビューを打ち切った感じ）

周りの人は意外と最後の粒度までしっかりやっているっぽかった。




# 個人的な疑問
## 設計自体のレビュー
「ドキュメント（設計書）のレビュー」はこの観点だと思うけど、「設計自体のレビュー」は、上記表現では足りていない観点がある気がする。
もう少し具体的な観点を見ている？みたいな？
それが何かはまだ言語化できてないけど、ぼんやりそんな気がする。


## レビューア育成
思えば、「[間違いだらけの設計レビュー](http://www.nikkeibp.co.jp/seminar/atcl/cn/nos180713/)」の研修に行ったことあるくらいで、周りの人とレビュー方法とかって話したことない気がする。

みんなどうやって自分のレビュー方法を確立しているのだろうか？


## レビューのタイミング
自分の場合、観点の「目的理解」に該当する部分が出来上がった時点で、一度見せれば良いのだろうけど、なんだかんだ最後まで作り切ってから見せてしまうことが多い気がする。

それは、自分が作るドキュメントが、目的自体がふわふわしている系のドキュメントが多いからだろうか・・・
（提案書作成のための調査検討資料とかを作ることが多い）

ドキュメントというか、会話ですり合わせることが多いから、大きな手戻りがないのかな・・・？

成果物作成までのタイミングを客観視した時に、どのタイミングでレビューを入れた方が良いかは、そのドキュメントのタイプや、その人のスキルによる気がするなぁ。


# 最後に
最後の語り合い2時間がとても濃かった！面白かった！

今回の勉強会を同じテーマ/同じやり方で、社内でやっても面白そうだなと感じた。
特に、ベテランから若手へのスキルトランスファーに良いんじゃないかなとか思った。

この記事だけを説明するのだけでは絶対に伝わらない感じがするので、どっかでタイミングを見つけて勉強会やってみようかな？とか思っている。


以上です。

---