こちらはトレタAdventCalendar2023 18日目の記事です。
こんにちは、トレタでトレタO/Xという飲食店向けモバイルオーダーのプロダクトマネージャーを行なっている北川です。
前回の記事で私がプロダクトマネージャーとして日頃行っている仕事内容について書きましたが、今回はプロダクトマネジメントの仕事の中で半分くらいの割合を占めている仕様書を書くというドキュメンテーションについてまとめたいと思います。
とはいえ、今のやり方がベストプラクティスとはまだ考えておらず日々アップデートをしつづけている最中です。ドキュメンテーションのやり方は組織や人によって千差万別だと思うので、あくまでも一つの例としてドキュメントライティングをしている人の参考になればと思います。
TL;DR
この記事では以下の内容について記載しています。
- 合意形成のために書く仕様書の内容
- 開発チームに伝える仕様書の内容
仕様書の粒度
おおまかな開発プロセスは前回の記事で書いた通りで、主に要件定義のフェーズと開発フェーズの2つのフェーズに分けられますが、仕様書を作成するのは基本的には要件定義のフェーズで行います。
要件定義フェーズで作成する仕様書はプロダクトのステークホルダー（プロダクトオーナー、セールスメンバー、リードエンジニアなど）との合意形成を行うための「機能仕様書」と、決まった仕様から各開発チーム向けに詳細を記載した「ユースケース仕様書」の2種類に分けています。
これはそのドキュメントの想定する読者と記述の粒度が異なるために分けています。 それぞれについて説明していきます。
機能仕様書
機能仕様書では、ロードマップやユーザーFBなどのバックログにあるイシューから具体的にどう実現するかを仕様として記述したものです。
多くの場合はこの仕様書をもとにステークホルダー（プロダクトオーナー、セールスメンバー、リードエンジニアなど）を集めたミーティングを開催し、仕様として問題がないか、スケジュールとしていつ頃着手するのか、などの内容を決定し合意形成を行います。
そのため、作成段階ではタイトルに[Draft] と付けてまだ仕様としてFixしていないことを表します。
定形のフォーマットは定めていませんが、主に以下の内容を記載します。
概要
要件
機能要件
非機能要件
対応案
影響範囲
比較表
議事録
目的と結論を冒頭にまとめる
今回の記事でもTL;DRを書きましたが、先頭にその仕様書の目的をまずは書きます。これは弊社で技術顧問を行っていただいているRyosuke Iwanagaさんのやり方を参考にさせていただいています。
仕様書として細かく書いても全員が隅から隅まで読んでくれるとは限りません(大抵の人は流し読みします)。なので冒頭にこの仕様書は何を解決するための内容で、結論としてどういった仕様にしようとしている、というのをなるべく簡潔に書くように心がけています。
非機能要件も忘れずに
何を解決したいのか、達成したいかを要件としてまとめて箇条書きなどで書くことで、議論が発展して脱線仕出した時に、そもそも解決したいことって何でしたっけ？と振り返るときに有用です。
この時に考慮が漏れがちなのが非機能要件です。機能要件はユーザーからのフィードバックなどの基のイシューから導出しやすいですが、非機能要件は顕在化されていない場合があります。
例えば、将来的に似たような問題が発生したときも考慮すべきかといった拡張性やメンテナンス容易性であったり、個人情報などを含まないかなどのセキュリティの面などを洗い出しておく必要があります。
松竹梅の比較表を設ける
実施工数や拡張性をどこまで重視するかで対応案が複数になるケースがあります。その場合はPros/Consをまとめた比較表を作り最終決定者が選択しやすいようにいわゆる松竹梅の3プランにまとめます。ここでのポイントは、中間の竹プランが選ばれやすいので誘導したいプランを軸にして松と梅を添えます。これはアンカリングと呼ばれる認知バイアスを利用した手法です。
割れ窓を取り急ぎ塞ぐ程度の場当たり的な対応は梅プラン、あまり負債も作らずに最小限で達成できる対応を竹プラン、たっぷり工数をかけて将来性含め完璧に対応するのを松プラン、といった形です。
意思決定の経緯を残す
仮に仕様書がなかったとしても、仕様を基にアウトプットされたアプリケーションコードなどから仕様を逆引きすることはできますが、なぜその仕様になったのかを探ることは難しいです。
どのような議論が行われ、どのような意思決定が行われたのかを議事録として記述または議事録のリンクを貼ります。
ユースケース仕様書
ユースケース仕様書は、前述の機能仕様書から各チーム向けにブレイクダウンした内容の仕様書です。名前の通りユースケースの粒度で作成しているので、「ユーザーが商品を新規登録する」などのタイトルの仕様書になります。画面仕様書ではなくユースケース単位にすることで、ユーザーはどういった目的をもっていて、どういったUIを操作し、システムはどうふるまうのか、といった一連のUXをまとめることができます。
ユースケース仕様書は、開発チーム内のメンバーの認識を一定に揃えるために記述します。読者としてはエンジニア、QAエンジニア、カスタマーサクセスのメンバーを想定しています。それぞれのメンバーは仕様書を基にアプリケーションコードやテスト計画書、ユーザーマニュアルをアウトプットとして作ります。それぞれのアウトプットに齟齬が生まれないように、誰が読んでも同じ理解ができることを意識して仕様書を記述します。
ユースケース仕様書はユースケースの分だけ書くことになり量が多いため、書式はテンプレート化しています。テンプレート化はかなり試行錯誤して改良を重ねていますが、一つ参考にしたのは「UI Spec」という書式です。こちらも同様にユースケースをベースとした書き方となっています。
ユースケース
要件
画面仕様
Figmaへのリンク
画面デザイン
遷移元
表示形式/入力形式
インタラクティブ項目
バリデーション
ユースケース
「誰」が「何」を「どうする」を記述します
例. ユーザーが商品を新しく登録する
要件
どういったアウトプットが期待されるかを記述します。E2Eテストの各シナリオのような記述をします。（テストコードでそのまま”describe”と”it”になると理想的）
例.
- 商品を登録できること
- 不正な入力をすると商品が登録されないこと
画面仕様
Figmaのデザインのリンクとスナップショットを貼りつけます。
リンクだけではなくなぜスナップショットなのは、常にFigmaと完全に同期が取れない可能性があるからです。 この仕様書は仕様変更があった際に随時アップデートしていく仕様書です。理想的にはFigmaと同時に更新されるべきですが、どうしても片方が更新漏れになってしまうこともあります。
そのため仕様書内の記載で齟齬が起きないようにスナップショットを添付しています。
表示形式・入力形式
Figma内で記載しきれない細かな内容を記述します。
- 参照データ：データモデルとのマッピング情報
- 表示条件：非表示にする場合があれば、データモデルの値と条件式
一覧表示であれば、
- 表示順、ページネーション有無、表示件数
入力形式であれば、バリデーションの内容を記述します。
- 必須項目であるか
- 最小値/最大値があるか
- 正規表現などのフォーマット制限があるか
インタラクティブ項目
ボタンクリックなどのユーザーインタラクションによってどのような振る舞いをするのかを記述します
例.
- 保存ボタン: 登録を行い、一覧画面へ遷移する
- キャンセルボタン：一覧画面へ遷移する
バリデーション
上記の入力形式で記載した以外のバリデーション内容があれば記述します。主にサーバーバリデーションに近い内容となります。
例.
- 名前などが重複して登録できるか
- 登録件数の上限があるか
さいごに
このように私が業務で書いているドキュメントの書き方的な部分を紹介しましたが、冒頭でも書いたようにまだ自分でもこのやり方がベストプラクティスではないと思ってますし、まだまだ書式や運用方法を磨かなければいけないと思っています。
例えば今はNotionを使って書いていますが、Notionでは履歴管理の機能が足りないと感じていて追記した部分のみを伝える手段がなかったり、修正依頼を承認して反映するような運用が難しいのでGithubに移そうかと検討したりしています。
より良い開発手法の探究やプロダクト開発に興味がある方をお待ちしています。
