設計書のテンプレートを改善して運用してみた話

:::note info
この記事は「[LITALICO Engineers Advent Calendar 2024](https://qiita.com/advent-calendar/2024/litalico)」の22日目の記事になります:christmas_tree:
複数カレンダーがあるので是非ご覧ください！
:::

## はじめに
こんにちは、LITALICOでプラットフォームエンジニア部に所属している @m_sugane です。
業務支援システムの開発をしております。

開発するにあたって資料を触る機会が多く、気付いた箇所を修正していたらいつの間にかドキュメント修正大臣としてテンプレート改善の使命を与えられたのでこの度一新して試しに運用をしてみました。
その際、気に掛けたこと、運用してみた感想を書いていこうと思います。

## 改善が必要になった背景
### ユーザーストーリーベースの設計になっていない

私の所属する大規模な業務システム開発チームではユーザーストーリーを重視し、開発が行われています。LITALICO所属のデザイナーがUXを定義しながらプロダクトデザインを行い、それを元にPdM・開発・QAで話を重ねて設計を進め、開発をしていくプロセスをしています。

ではユーザーストーリーとは何なのでしょうか。
所属プロジェクトでは以下のようにフォーマットして検討をしています。
```
[誰（役割や立場）] は [機能] したい。
[（それにより）〇〇という利益や良いことがある] からだ。
```
`[ユーザー目線]`に立って考えた時に`[この機能]`を実装することで`[どんな価値がある]`のかを示しています。
ここでポイントなのはユーザー目線であるという事です。
仮に開発が進み、機能実装が完了してリリースをしていようとユーザーが求めている価値を満たしていなければそれは無駄な機能ということになります。

設計MTGやウォークスルーではデザインされたワイヤーを見て、
「ユーザーストーリーがあるからこういったデザインをしている」
「何故この機能が必要なのだっけ？→こういうユーザーストーリーがあるからだ」
という話がされています。

しかし、旧設計書にはユーザーストーリーと開発時の設計資料に紐付きがなく、機能にのみ言及されている状態でありました。
これは何故この機能が必要なのかが紐づかれていない状態になってしまっています。

:::note info
ユーザーストーリーについては、
@kazuis さんの記事で品質も交えた紹介をされていますので是非こちらも！
[SaaSプロダクトでのユーザーストーリーを活用したQAプロセスのトリセツ](https://qiita.com/kazuis/items/a3a50b7e80f8abe19e7e)
:::

### 作成・修正に対するコストが高く、メンテナンスされづらい状態になっている
旧設計書では機能設計書、画面項目定義、バリエーション、テストケースや参照資料が同ファイル上で一緒に纏まっており、１画面に対しての機能のボリュームが多いほど記載が煩雑になり、粒度も記載者によってバラバラなため、メンテナンスに対するコストが高い状態でした。

前項で話した通り、デザイナーがワイヤーを用意している時点で開発の走り出しは可能なため、ドキュメントを用意するコストよりも開発スピードを優先した結果、ドキュメントが更新されない状態にあったのも１つに理由であると考えます。


## テンプレート作成で重視したこと
- ユーザーストーリーと紐付きを持つ構成をしていること
- テストケース作成の工数をできる限り抑えたい
- 記載内容の粒度を記載者依存にさせない
- メンテナンスのコストを削減し、最新化をしやすくしたい

### ユーザーストーリーと紐付きを持つ構成をしていること
ユーザーストーリーに対し、どの機能で価値を提供できるのかわかる状態を目指す。
機能の追加、変更や削除が必要なった時にユーザーストーリーと機能の紐づきから要否の判断でき、根拠となるようにする。

### テストケース作成の工数をできる限り抑えたい
テストフェーズでテストケースを１から作成することを避ける。
テストケースを作成するにあたり、一定水準以上のテストケースを誰でも作成できるようにする。これは一定水準以外の観点で不足している品質担保に時間を使いたいためである。

理想はコピー＆ペーストで標準テストを用意できるのが理想である。
これはテストフェーズで品質を作るのではなく、もっと上流の段階でしっかり品質を考える義務を発生させたい。設計段階で考慮した結果が標準テストの品質となり、副次的にテストケース作成の工数削減にも繋がるようにする。

### 記載内容の粒度を記載者依存にさせない
ある程度同様な記載になるフォーマットを用意してブレ幅を少なくする。
また、標準テストのコピー＆ペーストでそのまま使えるような記述にする。

### メンテナンスのコストを削減し、最新化をしやすくしたい
テンプレートとしてメンテするべきシートは最低限の状態にする。
使用していないシート、記載しないまま残っていてノイズとなるシートを除外する。
作り込むよりもメンテナンスしやすさを重視し、60点ぐらいの出来からブラッシュアップしていく。

## 出来上がった設計書について
改善したテンプレートは３つの構成をしています。
- 要件マトリクス
    - 業務要件（ユーザーストーリーの洗い出し）
    - 機能要件（デザイナーのワイヤーを元にしたUXとユーザーストーリーのマッピング）
    - 非機能要件
- 機能設計書
    - 概要
    - 画面設計書
    - 必要に応じて追加の詳細資料
- テストケース
    - 機能設計書の画面設計書から項目をコピー＆ペーストできるテンプレート
    - 手書きでテストケースを追加する用のテンプレート

要件マトリクスではユーザーストーリーやアプリケーション全体についてを考えるドキュメントとしています。
業務要件はアプリケーションにおけるユーザーストーリーを一覧で記載しております。
機能要件はデザイナーが作成・更新した画面のUX要素に対して、どのようなストーリーが想定されているのかを記載しています。
【簡単な画面の機能要件のイメージ】
![スクリーンショット 0006-12-19 23.15.02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2634801/2b274492-6fa4-15e9-c7d4-981f1e746c32.png)

機能設計書は開発に必要な情報を管理しています。
機能要件の画面要素にてユーザーストーリーが記載されているのでコンポーネント単位で紐付けがされています。
画面設計書ではテストケースベースで記載をしておりコピー＆ペーストできるようにしています。
複雑な条件の場合には別シートで条件やパターンを用意して参照させる作りです。
【簡単な画面の画面項目のイメージ】
![スクリーンショット 0006-12-19 23.38.24.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2634801/bc1e8521-e7ca-53ff-5f27-13c6c3d3541c.png)

テストケースは機能設計書からコピー＆ペーストで単体テストを作れるようにしてみました。
設計書の段階でしっかり検討がされていれば単体テストはこちらで網羅して担保できる想定です。必要に応じて手書きで作成できるテンプレートも用意しています。
![スクリーンショット 0006-12-20 0.43.19.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2634801/cad35c96-3271-115b-d497-f9f170f6a4a8.png)

## 運用した結果と感想
１つのアプリケーション開発を本テンプレートで運用をしてみました。
結果としては元々解決したかったユーザーストーリーベースとの紐づきとメンテナンスのしやすさは改善されました。さらには画面項目からテストケースを誰でも作成できることで確実にテスト工数の削減に繋がっています。
個人的には最低ラインのテストケース水準が「人による」という状況を減らせたのは良い点であったと思います。

更にここでもう１つ良い点は画面設計書からコピー＆ペーストで作るテストケースにおいては必ず設計書の最新化しないとテストケースを用意できない仕組みになっているので更新をする必要があり、タスク化をしなくても自然とドキュメントが更新されるような作りになっていることです。

一方でメンテナンスし易さを意識していることで最低限のシート情報しか持っていないので「設計書」として必要情報が足りているかは気になりますし、画面設計書や結合テストで記載されていない操作パターンでの不具合も発生したため、考慮できていないものの対策も検討していかなくてはなりません。

テストの自動化も視野にはあるのでどこを機械に任せ、どこを人で担保していくのかも考えていかなければと思います。１つずつブラッシュアップしていく必要があると感じています。

品質や機能についてユーザー目線で考えるタイミングが後ろになればなるほど出戻りと追加対応が発生してしまい、時間がない中で詰めて対応していくことになります。
作成したテンプレート構成はテストフェーズでテストケースを作りながら考え始めるのではなく、設計段階で考えながら作り始めるような形を意識しています。

より上位の工程で品質について意識して開発を進めることでユーザーに価値を提供していけるだけでなく、チーム全体の余裕を生み出すことができると思っているので意識して努めていきたいと思います。