USDM（要求仕様書を作成する時のお作法）の概要と、要求・理由・説明・仕様の書き方について、まとめてみました

# 1.はじめに
どうも、ARIの名古屋支社に勤務している愛知県民こと、
新藏（にいくら）と申します♪
(/・ω・)/

突然ですが、某日に私は
「自分は社会人5年目で、基本設計、詳細設計、単体テスト、結合テスト、移行、保守等々は
やったことあるけど、**ばっこり要件定義をやったことはないな・・・**」と考えていました。

何かしら勉強してみようということで、
**今回はUSDMの概要や書き方**について記事にしたいと思います！

要件定義、USDM等について勉強中の方の参考になれば幸いです。
(*^^)v

:::note info
私の勉強不足で厳密には違う点があるかもですが、悪しからず・・・
:::

---
ちなみに、12月は**ARIのアドベントカレンダ**もやっていますので、
もしよろしければ、こちらも応援お願いします♪

https://qiita.com/advent-calendar/2022/ari-group

https://qiita.com/advent-calendar/2022/aichi_lover_yomoyama


# 2.USDMとは
まずは、USDMの定義やメリット等について記載します。

**USDMとは、「Universal Specification Describing Manner」の略で、
要求仕様を定義するために使用するフレームワークのことです。**

USDMを活用することで正確な要求仕様を定義することができ、
**要求する人と作り手(開発者や設計者)のギャップを埋め、
手戻りや要求の不明確化を防止することができます。**

後ほど画像で説明しますが、要求と仕様を階層化する点が特徴的です。

また、USDMの起源は以下となります。

>USDMは、株式会社システムクリエイツの清水吉男氏が提唱しました。
>システムの要求と仕様をなかなかうまく定義できない現場向けソリューションとして提唱しています。
>いくつかの団体が標準もしくは推奨の要求定義方法として採用しており、信頼と実績があります。

引用：https://www.eureka-box.com/media/column/a19
 
# 3.USDMの構成要素
USDMは以下の4つの要素から構成されます。
次節以降ではそれぞれの要素の書き方について説明します。

**①　要求　→　目的語と動詞を使い、実現してほしいことを明確に記述する。
②　理由　→　認識のズレを抑えるために、その要求が必要な理由や背景を記述する。
③　説明　→　要求や理由の補足や、具体例や、用語定義等を記載する。
④　仕様　→　要求の実現方法、作るべきものに対する動きや制限を記載する。**

言葉だけだと少しわかりにくいと感じたので、
勉強中に私が試しで作ってみた要求仕様書を以下に記載します。

|![010_USDM概要.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1372071/1c4ccd17-6004-9939-2855-107fa9c3c3f7.png)|
|:--|

:::note info
要求は階層化し、上図では黄色が上位要求、青色が下位要求にあたります。
1つの上位要求に対して、複数の下位要求が存在する可能性もあります。
:::

:::note info
後で参照しやすいように、要求や仕様にはIDを振るのがお作法のようです。
:::

:::note info
Excelを使用することが多いようです。
:::

## 3.1.要求の書き方
**「要求」は、要求する人が実現してほしいことを明確に記述する項目となります。**

要求の書き方で特にポイントになる点は以下の2点となります。

### 3.1.1.「目的語＋動詞」で記述すること

### 3.1.2.①何が (何を)、②どんな状態において、③どうなっている時、③どうする、に分けて記載すること

また、3.1.2の①と④は必ず記載するのがお作法のようです。
以下に、具体例を示します。

■例その1

:::note info
Good
①冷蔵庫の扉が、②開いている状態で、③30秒経過した時、④警告音を鳴らす。
:::

:::note alert
Bad
冷蔵庫の扉が開きっぱなしになってしまう。
→　仕様となる動詞がないと何をしたいのか分からない（3.1.1の「動詞」がない）

温度を上げないように音を鳴らして知らせたい。
→　主語がないと、何を動かせばいいのかわからない（3.1.2の①がない）
:::

■例その2

:::note
Good
①車のワイパーを、③雨が降り始めた時、④自動で動かす。
:::

:::note alert
Bad
ワイパーを動かす。
→　どんな時に動かせばいいのか分からない（3.1.2の②がない）

雨がふったらフロントガラスの雨粒を取り除く。
→　主語がないと、何を動かせばいいのかわからない（3.1.2の①がない）
:::

### 3.1.3.要求は階層化すること

こちらは必須ではないですが、以下の図の様に
一つの大きい要求を分割することで、要求を単純化することもポイントとなります。

|![020_要求の階層化.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1372071/2b262b02-96da-9454-58e5-f7149748e435.png)|
|:--|

以上の3点を活用して、できるだけ丁寧に簡潔に書き、
要求する人と作り手との齟齬をなくしていきましょう♪
　 
## 3.2.理由の書き方
**「理由」は前節の要求が必要な理由や背景を記述する項目となります。**

理由を記載するのポイントは以下の1点となります。

### 3.2.1.要求する人の視点で考え、背景が分かる記載をすること

■例
「アラーム音を変更する」という要求に対する理由

:::note info
Good
アラーム音を好きな音に変更することで、飽きないようにするため。

対象の機器のアラーム音が、他の機器のアラーム音と似たような音のため。
:::

:::note alert
Bad
アラーム音を変更したいから。
→　要求と同じ文では背景が分からない
:::

なぜこの要求を実装したいのか、要求する人の視点から理由を記載することで、
要求する人と作り手との認識のズレをなくしていきましょう♪


## 3.3.説明の書き方
**「説明」は要求や理由の補足や、具体例や、用語定義を記載する項目となります。**

説明の書き方のポイントは以下の2点となります。

### 3.3.1.要求や理由の補足となるような、具体例や用語定義などを記載すること
### 3.3.2.必ずしも記載する必要はなく、補足したい情報がある場合のみ記載すること

■例
「アラーム音を変更したい」という要求に対する説明

:::note info
Good
デフォルトのアラーム音は、XXXという曲である。
→　補足となる情報が記載されている
:::

:::note alert
Bad
アラーム音を変更する際には、アラーム変更スイッチを押す。
→　要求または仕様に記載すべき内容である
:::

説明を記載して、より仕様を分かりやすくしましょう♪

## 3.4.仕様の書き方
**「仕様」は要求の実現方法、作るべきものに対する動きや制限を記載する項目となります。**

仕様の書き方のポイントは以下の3点となります。

### 3.4.1.要求の実現方法、作るべきものに対する動きや制限は、具体的に記載すること
### 3.4.2.作り手が誰であろうと、作成できるような具体的な文章で記載すること
### 3.4.3.複合的な要求にせず、できるだけ単純に記載すること

3.4.2について、「特定の人のみに伝わるような文にしない」ということですね。
また、3.4.3について、要求が複合的な場合は、いくつかに分けて仕様を記載することが必要となります。
以下に具体例を記載します。

■例
「アラーム音を変更したい」という要求に対して

:::note info
Good
1.アラーム音変更ボタンがクリックされたら、保存済の曲リスト一覧を表示する。
2.保存済の曲リスト一覧から、ある1曲がクリックされたら、試用として10秒再生する。
・・・
:::

:::note alert
Bad
1.アラーム音変更ボタンがクリックされたら、保存済の曲リスト一覧を表示する。
2.保存済の曲リスト一覧から、曲が選ばれた後、試用として再生する。
→　曲の選び方、試用として何秒再生されるのかが具体的でない（3.4.1に違反）

1.アラーム変更フラグが1になった場合は、保存済の曲リスト一覧を表示する。
2.保存済の曲リスト一覧から、ある1曲がクリックされたら、試用として10秒再生する。
→　フラグの説明の記載がない場合は、作り手が理解できない（3.4.2に違反）

1.アラーム音を変更したい場合は、保存済の曲リスト一覧を表示した後、1曲がクリックされたら、試用として10秒再生する。
→　複数の仕様が記載されていて分かりづらい（3.4.3に違反）
:::

誰でも同じイメージができるような、具体的な実現方法を記載し、
要求する人と作り手の認識齟齬をなくしましょう♪

# 4.おわりに
ここまで読んで下さり、ありがとうございます！！！
(^^)

今回は要件定義に関する内容ということでしたが、
「仕様」の書き方はテストの仕様書等にも応用できそうと感じました♪

私が記載する側になった際には、今回の内容を思い出して、
誰が見ても理解できるような要求仕様の作成を心がけたいです。

次回も何かしら記事にするので、お待ちください♪
(:3_ヽ)_