はじめに
先日こんなツイートを見かけました。
期待値を大きく外してきた成果物に対してどのように対応するかという問題についてのツイートでした。
このツイートのレビュー依頼者は「まずい点」を指摘してもらって修正すれば成果物として成立すると考えているけれど、レビュワーから見ると評価できる点がなくこのままでは成果物として成立させることができないと考えているように読み取れます。
7-8割程度期待値を満たしているものに対してのレビューであれば、レビューによって修正して成果物として成立させることができ、また、考え方を伝えることで次回からの成果物の質も上げられるでしょう。
一方で、期待値を全く満たしていない成果物に対してのレビューは、レビュワー、レビューイともに大きな苦痛を与えます。
懸命に作ったものを跡形なく直されるのは辛いですが、懸命に作ったものを跡形なく直すのも同じぐらい辛いです。
7-8割程度期待値を満たしてからレビュー依頼に出す、または、ポイントを絞って質問をしながら進めればこのような悲劇は回避できるはずですが、なぜ評価できる点がないものがレビュー依頼されるのでしょうか？
ChatGPT先生にヒントをもらいながら考察してみたいと思います。
外部設計作業を考察
あるウェブシステムについて、要件定義書から外部設計書を作成する作業で考えてみることにします。
- (わたし)
ウェブシステムについて要件定義書から外部設計書を作成しなければなりません。
必要な作業を教えてください。
- (GPT)
ウェブシステムの要件定義書から外部設計書を作成するためには、以下の一般的な作業手順を考慮できます。これらのステップは、システムの構造や機能を明確に文書化し、開発者や関係者にとって理解しやすい形に整理するのに役立ちます。
- 要件定義書のレビュー:
まず初めに、既存の要件定義書を詳細にレビューし、システムの主要な機能や要件を把握します。要件定義書が不完全な場合、ステークホルダーとのコミュニケーションを通じて不足している情報を収集します。- 外部設計の概要:
システム全体の外部設計の概要を作成します。これは、システムの全体的なアーキテクチャ、ユーザーインターフェース（UI）の概要、および主要なコンポーネントやモジュールの役割についての説明を含みます。- ユーザーインターフェース（UI）設計:
ウェブシステムのUIデザインを文書化します。画面のレイアウト、ユーザーコントロール、ナビゲーション、色、フォントなどの詳細を含みます。ユーザーエクスペリエンス（UX）を向上させるために、ユーザーフローとプロトタイプも考慮します。- 機能仕様の詳細化:
各機能やモジュールに関する詳細な仕様を文書化します。これには、入力と出力の形式、データ処理のロジック、エラーハンドリング、セキュリティ要件などが含まれます。UML図、フローチャート、シーケンス図などを使用してプロセスを視覚化することが役立ちます。- データモデルの設計:
データベーススキーマやデータモデルを文書化し、テーブル、関係、データのフロー、およびデータの整合性について詳細に説明します。- アーキテクチャと技術スタック:
システムのアーキテクチャと使用する技術スタックを明確にし、ハードウェアおよびソフトウェアの要件を文書化します。- 拡張性と保守性の検討:
システムの将来の拡張性と保守性を向上させるための設計を検討し、外部設計に反映させます。- セキュリティ要件:
システムのセキュリティ要件を文書化し、データ保護、アクセス制御、認証などのセキュリティ関連の要件を考慮します。- 外部設計書のドキュメンテーション:
上記の情報を整理し、外部設計書としてまとめます。一貫性があり、わかりやすい形式に整形し、図表やテキストで説明を補完します。- レビューと承認:
外部設計書を関係者や開発チームに提出し、レビューと承認を受けます。必要に応じて修正を加えます。- 外部設計の更新と保守:
システムが変更されるたびに、外部設計書を更新し、最新の情報を反映させます。これにより、システムの保守が容易になります。これらのステップを追跡し、外部設計書を丁寧に作成することで、ウェブシステムの開発と保守が円滑に進行し、関係者とのコミュニケーションも強化されます。
さすがGPT先生。かなり分かりやすい作業分類ですね。
業務によって過不足等ありそうですが、これがあれば考察できそうです。
外部設計書を作成してレビューするという作業は上記の 9, 10 にあたります。
レビュワーのインプットは、前工程で誰かが作成した要件定義書とレビューイが作成した外部設計書です。
考察を進めるため作業とレビュワーとレビューイが見るもの、作成するものを図に示しておきます。
どの作業に課題があるとレビューで跡形なく直るのか見えましたでしょうか？
課題のある作業と考察
1. 要件定義書のレビュー
跡形なく直る場合、最初の作業に問題があると考えるのが自然でしょう。
最初の作業が正しく実施できていなければ、その後に積み上がる作業は全部間違って無駄になる可能性が高いです。
このパートは逆転裁判1の調査パートのようなものです。地味で分かりにくい点も多いのですが証拠品を全て集めきらないと裁判パートで勝利できないです。裁判パートで勝利するためにも証拠品を全部かき集めましょう。
※ゲームではハマり回避のため証拠を集めきらないと裁判パートに進めない仕様でしたが。
- 要件定義書のレビュー:
まず初めに、既存の要件定義書を詳細にレビューし、システムの主要な機能や要件を把握します。要件定義書が不完全な場合、ステークホルダーとのコミュニケーションを通じて不足している情報を収集します。
「システムの主要な機能や要件を把握します。」 とサクッと書かれていますが、把握するには相当な訓練が必要です。
わたし達の日常生活では、ググって一番安い物を探したり、YouTubeをダラダラ見てLINEやツイッターで感想を投げつけ合うことはあるかもしれませんが、まとまった量の文章を読んで、それを理解して整理して誰かに分かりやすい形で伝えるということはしていないため、日本語の読み書きをする訓練が別途必要なのです。
また、自分では分かったと思っても 「本当に分かったのかは、本人では分からない」 ことも問題を複雑にしていそうです。
システムの把握の仕方には個人差があると思いますが、とりあえず資料には全て目を通して、これから作るシステムを脳内で（以後脳内システムと表記）動かしてヌケモレがないか確認して、ヌケモレがあれば必要な資料を更に探すか関係者に質問するなどする事ができるようになるとよさそうです。
2. 外部設計の概要
残念ながら「要件定義書のレビュー」の作業には成果物がありません。
一番手戻りが少なく、レビュワーに成果物ベースで確認を取れる最初の作業は「外部設計の概要」の作業となりそうです。
- 外部設計の概要:
システム全体の外部設計の概要を作成します。これは、システムの全体的なアーキテクチャ、ユーザーインターフェース（UI）の概要、および主要なコンポーネントやモジュールの役割についての説明を含みます。
「要件定義書のレビュー」作業で作った「脳内システム」の書き出しをするとよさそうです。
概要と、目次を並行して作成するイメージです。
概要には「脳内システム」が実現するシステムの主要な機能や要件を書きます。「こんな要件を満たしたいからこんな機能を持ったシステムを作ります」 という全体像を冒頭で説明し、システムについて何も知らない読者にシステムを理解してもらえるようにします。
概要のレビュー観点は「脳内システム」の整合性になります。脳内でシステムがある程度組み立てられていて、それを説明できるようになってくれば跡形なく直されることは減っていくと思います。
目次は外部設計書の骨組みです。この後何をどの様な粒度で説明していくかの指針が分かる程度に書けるといいでしょう。
章立てや粒度の構成はかなり基本的な技術であるにも関わらず、なぜか学校ではそれを訓練する機会があまり設けられていません。
『「脳内システム」を説明するための最良の構成』が必要であるため、他のプロジェクトの外部設計書などを参考にすることはできても、コピペで使えるテンプレなどは存在しません。
書いて、自分の課題を客観的に判断して、本屋に行って課題を解決できそうな本を買って読んでまた書いて…と試行錯誤を繰り返していくとよさそうです。
9. 外部設計書のドキュメンテーション
基本的な「仕様書文章力」がないと、全行修正されてしまい、結果として跡形なく直される原因となります。
これは字を読み書きすることでしか改善しません。
よさそうな本を買ってきて読んだり書いたりしてください。
例) amazon : 伝わる! 文章力が身につく本 (基礎からわかる"伝わる!"シリーズ)
絵がうまくなる方法と考え方は同じです。
本や人づてでテクニックを学ぶのも大事ですが、一番大事なのはたくさん読み書きすることです。字を読んだり書いたりする速さが上がれば試行錯誤できる回数も増えてレビューを受けられる回数も増え、改善の機会も増えます。
すぐに文章を作ったり直したりできる様になれば指摘されても直すことが苦痛ではなくなるので、痛みも減ります。
※個人的にはテクニカルな本を読むよりは、小説や漫画など好きな本を大量に読む方が苦しくなく続けらてよいのかなと思っています。小説や漫画には、分かりやすく効果的に人に物を伝えるテクニックの実例が大量に登場していますし。
おわりに
今回はレビューで跡形なく直される理由について考えてみました。
大きく以下３点の力を身に着けていくと跡形なく直されることは減っていく様に思えました。
- 要件定義を把握してシステムを組み上げる設計力
- 概要、骨組みを作成し理路整然と伝える構成力
- 仕様書文章力
跡形なく直される事を回避する一番のコツは「マメにポイントを絞って確認をとること」だと思いますが、それを実践するためには、「ある程度の構成力」や「ある程度の仕様書文章力」を身に着けておくことは必須となると思います。
相手には解決できない基本的な問題は先に解決しておかないと、相手に時間を使ってもらっても問題が解決できないからです。
設計力については、今見ているQiitaの外部設計を書き出してみるなどでも訓練になるかもしれません。存在しない新しいシステムの設計は答え合わせができないのと企画に時間がかかることから訓練には適さないと思います。
[3. ユーザーインターフェース（UI）設計] ~ [8. セキュリティ要件] についても色々ありますが「跡形なく直される」のテーマからは除外としました。
おまけ０
おまけ１（新卒エンジニア向け手紙）
おまけ２（新卒エンジニア向け記事）
おまけ３（パイセン向け記事）
おまけ４（...は難しいシリーズ）
おまけ５（営業A短編シリーズ）
おまけ６（エンジニアのためのお仕事問題集）
2030年にIT人材が最大79万人不足するとのことで、学習用の資料をgitで無料公開してます(不定期更新)。
よろしければどうぞ。