2023-10-27ドキュメント, 改善活動, 要件定義

楽曲配信サービスにおけるバックエンドシステムの保守及び運用業務をしている早坂です。

直近、チームとして改善活動を推進していく気運もあり、その一環として要件定義書のフォーマットを作成することとなりました。
要件とは何か、どのような項目を含めるべきか、など試行錯誤をしながら進めていましたので、体験記として記事にできればと思います。

本記事前半では、フォーマットを作成した背景や成果物について書きます。
後半では、フォーマットを作成するためにどのようなことを学び、考えたのかを書きます。

どんな改善を行ったのか

前提

私の担当するシステムに対する案件は主に機能の改修となるため、要件定義書も新規開発ではなく部分的な機能改修を目的としたフォーマットの作成としました。

改善対象となったチームの課題

• 何をすれば要求を満たしたことになるのかが明確に共通認識としてなかった
  • 改修案件は、要求仕様が降りてくると既存の設計書に修正を加えてすぐに実装に入っていたため、開発者個人の経験値やシステムの理解度に依存していた。
• なぜ現在のコードになったのかを辿る情報源がほぼなかった
  • 過去の対応案件とそれに付随する改修履歴がほぼなく、アーカイブできるドキュメントがなかったため、ソースコードだけ見てもなぜ現在の仕様になっているかがわからない。

なぜ要件定義書を作成するのか

• 要求を満たすためのアクションを言語化するのは要件定義の役割である
• 要件定義を作成することで、言葉で共通認識を持つことができる
• 現在のコードになった理由を示す情報源として、どのような要件があったのかを明記したドキュメントを残せる

なぜフォーマットを作成したのか

保守及び運用をしていく中で、今後も改修案件が発生することを鑑みてフォーマット化によるドキュメント作成コストの削減を狙った。

結果、どんなフォーマットになったのか

以下が現時点で最新のフォーマットになります。
[]で囲まれたものは項目名です。
各項目に対する内容の簡易な説明や例も記載しています。

本書で対象とする業務課題の章を設け、なぜ掲題の案件が必要なのか、現状はどうなっていて、理想とする状態はなんなのかを記載するようにしました。案件のゴールを言葉によって共通認識とし、前述の課題を解決できるような形にしました。

スコープ定義以降はシステムに関するお話となります。 スコープ定義は対象とするシステムの具体的にどこを改修対象とするのかを定義します。また、システムがどういった状態になっていれば良いのかを 業務課題解決の目的と達成指標で定義します。ここで定義する達成指標がシステムテストの観点として参考になる記述になります。 機能要件では、達成指標と対になる形でどんな機能があれば良いのかを定義します。

リファレンスは要件定義書中での引用や参照したドキュメントの一覧を記載します。 改善対象となったチームの課題の中で言及はしていませんでしたが、既存ドキュメントには関連するドキュメントのリンク付けがないため、探したいドキュメントが見つけづらい、という課題もありました。そのため、要件定義書中に参照一覧を設け、紐づくドキュメントを関連付けました。

試行錯誤

この章では、前述した要件定義書のフォーマットができるまで何をしていったのかを書いていきます。

主に要件定義を作成するためにどのようなことを学習したのか、構成はどのような考えで決めたのかを書きます。

まず何をしたか?

要件定義書のフォーマットを作成するにあたって、まずチームリーダーから参考としてIEEE(the Institute of Electrical and Electronic Engineers)が提供しているSRS(Software Requirements Specifications)を提示されました。

そもそも要件定義とはどのようなこと書くのか知らなかった私は、SRSを解釈するところからタスクを開始しました。しかし、SRSは新規開発向けのフォーマットであり、システム開発における目的設定からユーザー定義、ソフトウェアやハードウェアのインターフェース定義など網羅的に項目が羅列していました。そのため、改修案件に適用でき、かつチームでの課題解決につながるようにテーラリングする必要がありました。

テーラリングにあたって、一般的な要件定義書の意義や記載するべき内容について調べ、自分なりに理解を深めることを出発点としました。

アクション1:要件定義とは何かを調査

Web記事や書籍を通じて要件定義に関する理解をしていきました。

Web記事は正確性が保証できなかったり、そもそも情報が不十分であったりする側面がありますが、一旦どのような概念があるのか確認する程度なら十分だと個人的に感じています。なので、まずはWeb記事を読んでざっくりと理解した上で、より体系的かつ正確と思われる書籍に移って勉強していきました。

すべて書くと重複する点や記事が長くなるので一部を記載します。

Web記事

以下の記事を見つけたので拝読。特に勉強になった点を引用します。

要件定義～システム設計ができる人材になれる記事

要件定義を決めるプロセス

• 要望：「こんなシステムがあったら良いな」といったアイディア
• 要求：システムに実装して欲しい大まかな機能一覧
• 要件：双方が合意した具体的な機能一覧と実装方法

次に、要件定義で決める事項については以下のような記載がありました。

• Why：システム開発の目的（要望）
  • 現状の課題
  • ゴール（本来あるべき状態）
  • 現状とゴールのギャップ（解決すべき課題）
• What：どのように課題を解決するのか
  • システム導入後の業務フロー
  • 機能要件
    • システムに実装する機能一覧
  • 非機能要件
    • 処理スピード、セキュリティ など様々
• How：具体的な使い勝手と実装方法（システム設計に近いタスク）
  • 基本設計
    • 画面設計（UI設計）
    • 機能設計
    • データ設計
  • 詳細設計
    • クラス図、シーケンス図
    • システムアーキテクチャ
    • 各部位を実装する技術 など様々

要件というのは概念的にどこに位置するのかを理解しました。
また、要件定義書を作成するために何を解決するのか、何を作るのかというWhatに着目するべきだということを学びました。

書籍

体系的に理解するべく、以下の書籍を購入して読んでいきました。

羽生章洋. はじめよう！ 要件定義 ～ビギナーからベテランまで (Japanese Edition)

前述したようなWeb記事の内容に加えて具体例も含めて理解できる、とてもわかりやすい書籍でした。
この本を読んで、さらに気付きがあった点を引用します。

上流工程と実装とは別物であるから、実装技術を決めなくても要件を定義することはできるという意見もありますが、ではそこでいう要件とは具体的にはいったい何なのか、それを決めることで後工程に何を送るのか、ということを曖昧にしたままもっともらしい言葉で誤魔化すのは、プロジェクトに火種を持ち込むだけです。基本的な実装の裏付けはこの時点で用意しておきましょう。

要件定義で実装技術などの曖昧性を残しておくと、それがプロジェクトの火種となると警鐘を鳴らしていました。具体的に道具を使ってどういった機能を作るのかを定めるのは、要件定義よりさらに下流の基本設計、詳細設計になるかと思いますが、どんな道具を使って要件を実現するのかは認識をそろえておく必要があるのだと知りました。
今回の改善活動で考えると、何をすれば要求を見たせるのかを明確にすることが重要と解釈しました。
また、この書籍では要件定義に記載する項目を”UI”、”データ”、”処理”と3つに大きく分解しており、この順番で定義を進めていくと良いという主張も勉強になりました。作成したフォーマットにデータの定義に関して記載する項目は設けていませんが、扱うデータに着目して文面を記述するよう心がけることを学べました。

アクション2:要件定義の定義

要件定義に関する情報を一通り得た上で、自分なりに情報を解釈し、要件定義とはなんなのかを定義しました。

改善対象となったチームの課題で前述した課題を解決するために、必要な要件定義の範囲を決定することとしました。今回は以下のWhatを記載するものとしています。

• 業務、またはシステム的な課題
• 課題を解決するためにやるべきこと
• やるべきことをするにあたり発生する制限

課題の提起とそのためのアクションを明確にすることを目的として、具体的にどうするのか(How)は記載しないとしました。また、課題を解決するためにやるべきことを明記することは、同時に制限事項の考慮ややらなくていいことを考えることにもなると思いました。

アクション3:項目の策定

SRSを参考にし、最初に作成したフォーマットは以下になりました。

前述した最終的なフォーマットよりも記載事項が非常に多いです。最初からフォーマットに記載する項目を最小限にするよりも使ってみてから不要なものを削除する考えの方が効率的と考えました。とはいえ、今考えるとSRSの内容を踏襲しすぎたと感じています。。

※ インジェスト要件はシステムに対するインプットデータの要件、 デリバリー要件というのは外部システムに出力するための要件になります。

アクション4:試作として使いつつ改善する

実際に使いながら修正していく前提で作成していたのもあり、私が主導となった案件で、前項で決定したフォーマットを使い要件定義書を作成しました。作成した要件定義書をチームメンバーにレビューしていただき、以下の修正が入りました。変更理由も合わせて記載します。

削除した項目

• 非機能要件
  • 理由→非機能要件に関する改修がほぼ入らない
• 外部インターインターフェース
  • 理由→改修対象となることが非機能要件と同様にない
• システム鳥瞰
  • 理由→システムの基本構成は変わらないので、どの案件でも記述が同じになる

変更した項目

• 機能要件
  • 修正内容
    • インジェスト要件、 デリバリー要件をまとめ、案件で解決したい課題を解決手段として 機能要件を記載する
  • 理由
    • 必ずしもシステムに対する入出力の定義が要件として入るとは限らない
    • 機能要件がなぜ必要になったのかをわかるようにしたい
• 概要
  • 修正内容
    • 概要ではなく、具体的にシステム要求事項や課題を見出しにする
    • スコープ定義は別項目にする
    • リファレンスは 付録と合併する
  • 理由
    • 見出しはドキュメントの重要な骨組みなので、見出しだけでも記載内容がイメージできるようにしたい
    • 見出しの名前に変更が入るので、それに伴って適切に記載内容を分散させたい

以上の経緯で、本記事前半に載せた最新版のフォーマットが作成されました。

まとめ

チームの改善活動の一環として実施した、要件定義書のフォーマット作成タスクの体験を記事にしました。定量的な効果測定はできていませんが、要件定義書によって要件は何かを言葉にして共通認識を生む流れはできたのではと思っています。
要件定義について勉強できたことはもちろん、フォーマット作成そのものを通してドキュメント作成における骨組みの重要性を知る良い機会となりました。
今までエンジニアはシステムを構築していくことが大きな役目だという認識が自分の中に大きくありましたが、こういったチームの課題を解決するアクションを取ることもエンジニアとしての役割であることを再認識しました。

今後も要件定義書のフォーマットは改善していきつつ、今回のようにチームが持つ課題の解決にアプローチしていければと思います。

最後までお読みいただきありがとうございました。

この記事を書いた人

早坂啓太

最近書いた記事

• 2023.10.27改善活動の一環として要件定義書のフォーマットを作成した話
• 2022.12.11Spring FrameworkのDI
• 2021.12.24データ分析未経験の新卒エンジニアがレコメンド機能を実装した話