ブログ

ryuzeeによるブログ記事。不定期更新

ドキュメントレビューをする際の10のポイント

みなさんこんにちは。@ryuzeeです。

重厚長大なドキュメントは、動かなかったり嘘が書いてあったり現実と異なっていたり、その上肝心なこと書いてなかったりということで辛いことが多いのが現状です。 今回とある筋からドキュメントをレビューする際のポイントを教えて欲しい、という依頼を受けたので書いてみます。

なお、個人的には、ドキュメントレビューよりソースレビューの方が重要だと思っています。

とはいえドキュメントレビューで肝心なのは、

  • ドキュメントレビューをするなら、その投資に見合う何を得るのか?を決めておく必要がある
  • 本当にそのドキュメントは必要か?をよく考える(会社のルールだから!というのは理由にはなっていない)

だと思います。

レビューのポイント

1. 体裁をレビューするのではなく、中身をレビューする

ひどい現場だと、文書のインデントやフォントのサイズ、誤字脱字ばかりを重箱の隅をつつくようにチェックしているケースがあるようです。 しかし、そうではなく中身をレビューする必要があります(ただしあまりに体裁がひどい場合は、往々にして中身もひどい場合も多いようですが・・・)。 中身が分からないから体裁をレビューする、というのもあるようですが、そのレビューの結果は、どんな利益を生んでいるのかよく考えるべきです。 なお、レビューワーはレビュー前に資料を確認しておくべきであることは言うまでもありません。 いきなり初見の資料を見てレビューできる項目はたかがしれています。

2. 標準化ではなく、顧客や案件ごとに最適化できるような自由度をチームに与える

必要なドキュメントは顧客毎、システム毎に異なります。

常に自社の標準に無理やり押し込めようとするのではなく、案件特性や顧客特性を踏また上で、どのようなドキュメントが必要なのかは最初に考えてください。 そしてドキュメントも常時リファクタリングできるようにしていきましょう。

3. レビューの目的を明確にする

レビューは実施することに意義があるのではなく、そこで問題となりそうなことを早期に検出し、将来のリスクを軽減することに意味があります。 レビューワーの時間、参加者の時間を投資するので、その投資に見合うリターンを生むようにしなければいけません。

4. 大がかりなレビューを少ない回数実施するのではなく、こまめな小規模レビューを繰り返す

アジャイルなレビューです。 大量に作ってしまった問題あるドキュメントを修正するのは簡単なことではありません。 リスクを早期に検出しクリアにするためには早期レビューと繰り返しが必須です。 次の工程に入る前にとってつけたようなレビューをして、条件付きで承認をする、といったやり方をするチームもありますが非効率で、問題の先送りである。

5. レビューでの指摘事項をすべて対応しなければならないとは限らない。チームにとって労力をかけるだけのメリットがあるものから優先順位付けをして実施する

レビューワーは気づいた点を大小問わずすべて指摘するかもしれませんが、それを全て修正する必要が必ずしもあるとは限りません。 修正にかけるコストと効果を勘案し、優先順位をつけて対応すれば良いでしょう。

6. レビューで人格を非難しない

ついついレビューワーは上から目線で、「こんなこともできないのか!」みたいなトーンで指摘してしまいがちです。 そういうことをしていると、レビューを受ける側は、レビューを通りさえすれば何でもいいや、と思うか、レビューを受けることすら嫌がるようになります。 レビューをする側も、顧客へ届ける製品の品質の一旦を担っていると考えられるので、同じ土俵の上で純粋に同じゴールに向かってレビューしてください。

7. レビューの順番もレビュー効果が高いものから実施すること

同じフェーズの設計書でも、システム内での機能の重要度には差があるはずです。 全部が重要な機能である、というシステムはいまだかつて見たことがありません。 限られた時間の中で最大の効果を出すためには、アジャイルで構築するフィーチャーに優先順位をつけるのと同様に、レビューする範囲にも優先順位をつけてください。 レビューでは100%のレビューカバレージを取ることが目的なのではなく、問題を早期に検出し、将来にリスクを顕在化させないようにするためのものなのです。

8. 機械的に検証可能なドキュメントのレビューは自動化すること

体裁にこだわっても仕方ないですが、字面しか見ないようなチェックであれば、perlのスクリプトなんかでも十分チェックできます。 それこそソースコードをコミットする際に、自動でCode Snifferかけるようなもので良いでしょう。

9. レビューワーも技術もしくは顧客の業務をしっていること

技術を知らないとアーキテクチャの妥当性や注意すべきポイントの指摘ができません。 業務を知らないと仕様の妥当性が理解できません。 どちらも知らない人がレビューしても字面チェックしかできないので時間の無駄です。

10. レビュー結果はチーム内外含めて共有すること

レビューの結果の中で有意義なものがあれば、チームの中で最大限活用すれば良いでしょう。 指摘項目の中で簡単に自動チェックできるようなものがあれば自動化も検討してください。

ソースコードのレビューもほぼ同じことが言えると思います。

アジャイルコーチングやトレーニングを提供しています

株式会社アトラクタでは、アジャイル開発に取り組むチーム向けのコーチングや、認定スクラムマスター研修などの各種トレーニングを提供しています。ぜひお気軽にご相談ください。

詳細はこちら
  • スクラム実践者が知るべき97のこと
  • 著者/訳者:Gunther Verheyen / 吉羽龍太郎 原田騎郎 永瀬美穂
  • 出版社:オライリージャパン(2021-03-23)
  • 定価:¥ 2,640
  • スクラムはアジャイル開発のフレームワークですが、その実装は組織やチームのレベルに応じてさまざまです。本書はスクラムの実践において、さまざまな課題に対処してきた実践者が自らの経験や考え方を語るエッセイ集です。日本語書き下ろしコラムを追加で10本収録
  • プロダクトマネジメント ―ビルドトラップを避け顧客に価値を届ける
  • 著者/訳者:Melissa Perri / 吉羽龍太郎
  • 出版社:オライリージャパン(2020-10-26)
  • 定価:¥ 2,640
  • プロダクト開発を作った機能の数やベロシティなどのアウトプットで計測すると、ビルドトラップと呼ばれる失敗に繋がります。本書ではいかにしてビルドトラップを避けて顧客に価値を届けるかを解説しています。
  • SCRUM BOOT CAMP THE BOOK 【増補改訂版】
  • 著者/訳者:西村直人 永瀬美穂 吉羽龍太郎
  • 出版社:翔泳社(2020-05-20)
  • 定価:¥ 2,640
  • スクラム初心者に向けて基本的な考え方の解説から始まり、プロジェクトでの実際の進め方やよく起こる問題への対応法まで幅広く解説。マンガと文章のセットでスクラムを短期間で理解できます。スクラムの概要を正しく理解したい人、もう一度おさらいしたい人にオススメ。
  • みんなでアジャイル ―変化に対応できる顧客中心組織のつくりかた
  • 著者/訳者:Matt LeMay / 吉羽龍太郎、永瀬美穂、原田騎郎、有野雅士
  • 出版社:オライリージャパン(2020-3-19)
  • 定価:¥ 2,640
  • アジャイルで本当の意味での成果を出すには、開発チームだけでアジャイルに取り組むのではなく、組織全体がアジャイルになる必要があります。本書にはどうやってそれを実現するかのヒントが満載です
  • レガシーコードからの脱却 ―ソフトウェアの寿命を延ばし価値を高める9つのプラクティス
  • 著者/訳者:David Scott Bernstein / 吉羽龍太郎、永瀬美穂、原田騎郎、有野雅士
  • 出版社:オライリージャパン( 2019-9-18 )
  • 定価:¥ 3,132
  • レガシーコードになってから慌てるのではなく、日々レガシーコードを作らないようにするにはどうするか。その観点で、主にエクストリームプログラミングに由来する9つのプラクティスとその背後にある原則をわかりやすく説明しています。
  • Effective DevOps ―4本柱による持続可能な組織文化の育て方
  • 著者/訳者:Jennifer Davis、Ryn Daniels / 吉羽 龍太郎、長尾高弘
  • 出版社:オライリージャパン( 2018-3-24 )
  • 定価:¥ 3,888
  • 主にDevOpsの文化的な事柄に着目し、異なるゴールを持つチームが親和性を高め、矛盾する目標のバランスを取りながら最大限の力を発揮する方法を解説します
  • ジョイ・インク 役職も部署もない全員主役のマネジメント
  • 著者/訳者:リチャード・シェリダン / 原田騎郎, 安井力, 吉羽龍太郎, 永瀬美穂, 川口恭伸
  • 出版社:翔泳社( 2016-12-20 )
  • 定価:¥ 1,944
  • 米国で何度も働きやすい職場として表彰を受けているメンローの創業者かつCEOであるリチャード・シェリダン氏が、職場に喜びをもたらす知恵や経営手法、より良い製品の作り方などを惜しみなく紹介しています
  • アジャイルコーチの道具箱 – 見える化の実例集
  • 著者/訳者:Jimmy Janlén / 原田騎郎, 吉羽龍太郎, 川口恭伸, 高江洲睦, 佐藤竜也
  • 出版社:Leanpub( 2016-04-12 )
  • 定価:$14.99
  • この本は、チームの協調とコミュニケーションを改善したり、行動を変えるための見える化の実例を集めたものです。96個(+2)の見える化の方法をそれぞれ1ページでイラストとともに解説しています。アジャイル開発かどうかに関係なくすぐに使えるカタログ集です
  • カンバン仕事術 ―チームではじめる見える化と改善
  • 著者/訳者:原田騎郎 安井力 吉羽龍太郎 角征典 高木正弘
  • 出版社:オライリージャパン( 2016-03-25 )
  • 定価:¥ 2,138
  • チームの仕事や課題を見える化する手法「カンバン」について、その導入から実践までを図とともにわかりやすく解説した書籍。カンバンの原則などの入門的な事柄から、サービスクラス、プロセスの改善など、一歩進んだ応用的な話題までを網羅的に解説します。
  • Software in 30 Days スクラムによるアジャイルな組織変革“成功"ガイド
  • 著者/訳者:Ken Schwaber、Jeff Sutherland著、角征典、吉羽龍太郎、原田騎郎、川口恭伸訳
  • 出版社:アスキー・メディアワークス( 2013-03-08 )
  • 定価:¥ 1,680
  • スクラムの父であるジェフ・サザーランドとケン・シュエイバーによる著者の日本語版。ビジネス層、マネジメント層向けにソフトウェア開発プロセス変革の必要性やアジャイル型開発プロセスの優位性について説明
  • How to Change the World 〜チェンジ・マネジメント3.0〜
  • 著者/訳者:Jurgen Appelo, 前川哲次(翻訳), 川口恭伸(翻訳), 吉羽龍太郎(翻訳)
  • 出版社:達人出版会
  • 定価:500円
  • どうすれば自分たちの組織を変えられるだろう?それには、組織に変革を起こすチェンジ・マネジメントを学習することだ。アジャイルな組織でのマネージャーの役割を説いた『Management 3.0』の著者がコンパクトにまとめた変化のためのガイドブック