はじめに

私の業務は QA (Quality Assurance:品質保証）です。
組織によって QA の業務内容は異なりますが、私の組織では以下の3つ業務を担当します。

ドキュメントレビュー(仕様書や設計書の内容を確認)
プロセスチェック（社内・業務規定に従って作業していることを確認）
製品テスト（製品が仕様・設計通りに動作することを確認）

ドキュメントレビュー中に「どうしてチームや人によって、設計書の完成度に差が出るんだろう？」とふと疑問に思ったので、自分なりに整理してみました。

そもそも、なんで「設計書の完成度」を気にするの？

端的に言うと、設計書の完成度が低いと 無駄なコストが発生する からです。
以下に、開発中・保守運用中それぞれのフェーズに発生する問題を列挙します。

開発中：要求定義～受入テスト

他の設計者「設計根拠や前提条件が記載されていないので、設計の妥当性を判断できない。そのため、設計内容に矛盾や不足があっても発見されないまま実装され、納品時に顧客の要件に適合しないことが発覚する。」
QA「設計書に必要な情報が不足しているので、顧客の要件やシステムの仕様に沿ったテストを作成できない。その結果、バグを見逃してしまい、顧客に納品した後トラブルとなる。」

運用開始後：保守～改修～廃棄

後任の設計者「コンポーネントや外部システムとどのように連携しているのかが設計書に記載されていない。そのため、ある部分を改修した際に与える影響範囲を特定できず、思わぬところに不具合が発生する。」
不具合対応の関係者「エラー処理や例外処理の内容が記載されておらず、内部の挙動がわからない。そのため、不具合の原因の特定や対策に時間がかかる。」

完成度が低い設計書は、 関係者全員の時間と労力を無駄　にします。
だからこそ、関係者全員がスムーズに作業を進められる 完成度の高い設計書が必要 なのです。

「完成度が高い設計書」が生まれる過程を考える

設計書が生まれる過程から、「どんなスキルが必要かな？」と考えました。
考えた結果は下の表の通りです。

プロセス	作業内容	必要なスキル
論点・サブ論点	設計書の目的と章節構成*1を考える	論理的思考力
タスク	仕事を実行可能な単位に分割する*2	仕事の段取り力、コミュ力
スケジュール	タスクの優先順位と所要時間を考えて時間を確保する	自分の作業スピードを見積もる力
作業	集めた情報と決定事項を文章にする	テクニカルライティングのスキル＋セルフチェック（音読、校閲機能）
アウトプット	設計チームやQAのレビューを受ける	レビュースキル

*1)例えばセキュリティ設計書の場合、
まず前提条件となる設計書の対象範囲やシステム構成、顧客のセキュリティ要件や法規制等を記載します。そのあとに、セキュリティリスク分析を実施した結果を記載して、「どのようなリスクがあるのか。また、そのリスクにはどう対応していくのか。対応策を導入すると受け入れ可能なレベルまでリスクが低減されるのか。」という流れで、どんどん具体化していきます。この流れから外れると、ゴールが不明確になったり、論理性が失われます。

*2)タスクの中には、技術書からの情報収集であったり、ほかの機能を担当する設計者に質問したり、ネゴったり...いろいろ泥臭いこともあると思います。「設計者は一人でコツコツ作業することが好き」というイメージがありました。しかし、チームで働く以上、相手に依頼することであったり、進捗報告＋遅延の報告であったり、という風にコミュニケーションスキルは避けては通れないなと思いました。

コーヒーブレイク「コミュニケーションって難しい」

とある部署での開発プロジェクトは、以下の特徴があったのでプロジェクトが混乱することはほとんどありませんでした。

チーム全員が確立された開発プロセスに従っていたので、作業漏れが少なかった
開発チームの人数が少なく、情報共有がスムーズに行えていた
製品について熟知したメンバーが開発を担当していたため、仕様の理解不足や誤解が発生しづらかった

しかし、現在参画している開発プロジェクトでは様々な問題が起こっています。まとめると、上で述べたプロジェクトは正反対の特徴があります。

新しい開発プロセスに従っているため、チーム全員にとって不慣れなため、作業漏れが発生する
開発チームの人数が多く、必要な人に情報が回ってこないことがある
製品や製品が使用されるビジネスを理解しているメンバが少なく、仕様の理解不足や誤解が発生する

同じ会社であっても、部署やグループによって仕事の進め方や開発経験が異なります。そのため、関係者間で認識のズレが起こらないように、 ゴールや作業ルール、作業の担当範囲等　について、密なコミュニケーションが大事だなと思いました。

最後に

私の実体験に基づく偏った意見です。
実際に経験したことやアドバイス等ありましたら、コメント欄でご意見を頂けると幸いです！

参考文献

適宜、追加していく予定。

テクニカルライティング

技術者のためのテクニカルライティング入門講座

レビュー

なぜ重大な問題を見逃すのか？間違いだらけの設計レビュー第3版

ソフトウェアエンジニアリング

変更履歴

2024/12/18: 新規作成