📚

デジタルプロダクトに仕様書がいらない理由

2022/10/29に公開

仕様書

idea

概要

筆者はデジタルプロダクトに仕様書はいらないと考えています。
しかし、過去に関わった様々なプロジェクトで仕様書が書かれていました。
この記事では筆者が仕様書はいらないと考えている理由を示します。

仕様書とは？

筆者が不要だと考える仕様書とは一体どのようなものなのか定義します。

プロダクトの最新版の仕様が細部まで網羅的に書かれているドキュメント
Word、Excel、マークダウンといったファイルであったり、Googleドキュメント、Googleスプレッドシート、esa、Notion、Backlog Wiki、GitHub Wiki、といったWebアプリケーションで書かれている
主にシステムを運用するオペレーター向けに作られている

なぜいらないのか？

仕様書がいらない理由を以下に列挙します。

仕様書がないと困るようなUI/UXデザイン・実装をするべきではない

iPhoneが代表的ですが、近年のプロダクトはデジタルに限らず説明書が薄かったり、なかったりします。
説明書を見なくてもユーザーが直感的に理解できるようにデザインされているためです。

UIを見たら仕様を理解できる、あるいは仕様を理解しなくても使えるようにデザイン・実装されるべきです。

デジタルプロダクトに完成形はなく常に変化し続けるため、機能追加や仕様変更のたびに仕様書を更新する必要がある

仕様書の維持にはメンテナンスコストがかかります。

抜け漏れなく網羅的に母国語や表、図、画像などを用いて仕様を書くのは実際にやってみると想像以上にコストがかかるものです。
その上、そういった作業が苦手な人も少なくないように感じます。チームの体制によりますが、最初こそ丁寧に更新していたとしても徐々に更新されなくなったり参照されなくなるケースが少なくありません。

仕様書の信頼性が低いと仕様書があったとしてもオペレーターはエンジニアに仕様を確認する。といったことが起きます。

正しくない情報が書かれている仕様書があるよりは仕様書がない方がマシである

『誤って認識する』よりは『知らない（ので調べる必要がある）』状態の方が事故は起きづらいです。
誤って認識するとエンドユーザーやクライアントに間違った情報を伝えてしまうリスクがあります。

このリスクを避けるためには正しくない情報が書かれる可能性のあるものをできるだけ排除する必要があります。
一次情報を参照できるものに関しては一次情報を参照する方がリスクを低減できます。

プロダクトを見れば誰でもわかることをわざわざドキュメントにする意味はない

よくある意味のない仕様書には『プロダクトを見れば誰でもわかること』が書かれていることが多いです。

例:

# 管理者向けユーザー一覧ページ

- 管理者がユーザーを一覧で見るページです
- ユーザーを検索するためのフォームがあります
- 氏名、電話番号、メールアドレスで検索できます

# 管理者向けユーザー作成ページ

- 管理者がユーザーを作成するページです
- 氏名、電話番号、メールアドレス、パスワードを入力して登録ボタンを押下するとユーザーが作成されます
- パスワードは半角英数字が使用でき、8文字以上である必要があります

これはプロダクトのUIを見ればわかることですし、わからないとしたら仕様書を作るのではなくプロダクトのUIを改善すべきです。

仕様書を作らないとしてもやっておくべきこと

仕様書を作らないとしてもやっておくべきことを以下に列挙します。

オペレータ向けの手順書などを作る

仕様書を作っている人に『この仕様書はどういったときに参照されますか？』と聞くと、大抵の場合は『オペレータが作業する際に確認する』、『CS担当者が問い合わせに答えるために確認する』といった返答が返ってきます。

このような場合、作るべきなのは仕様書ではなくオペレータ向けの手順書であり、CS担当者向けのトークスクリプトです。
仕様書は仕様という客観的事実が記載されているだけなので、オペレータは仕様書から仕様を理解して自らの行う業務の場合はどのように対応すべきか考えることになります。
しかし、仕様書ではなくオペレータ向けの手順書があれば、オペレータは手順書を見てその通りに実行するだけです。『考える』という工程を排除できるのでオペレーションに個人差が生まれることを回避できます。

手順書を用意する場所に関しては、『プロダクトと切り離した個別の読み物』として用意するのではなく、実際にオペレータが操作する画面に説明が示されている方が好ましいです。
その方が『プロダクトそのものを見ればわかる』という状態に近く、オペレータが手順書を目にする機会が増えるので手順書の誤りに気づきやすいためです。（慣れてきたオペレータは手順書を見なくても操作できてしまうので、手順書が別で用意されていると閲覧機会が減り、それが手順書が古く更新されない原因になります。）

プロジェクト管理ツールのチケットでその時点の仕様の詳細を記載する

仕様書が不要であると考えつつも、開発の際は仕様を抜け漏れなく網羅的に考える必要があり、それを伝える必要があります。そのためプロジェクト管理ツールのチケットでその機能を実装する時点の仕様の詳細を記載します。
Figmaのデザインやスプレッドシートに整理したマトリクスなどがあればそれらへのリンクを記載します。

これは基本的に『作るために書く』ものですが、実際はその機能のリリース後に調査のためにチケットを確認することもあります。
エンジニアであれば想像しやすいですが、バグ発生時など特定の箇所の仕様を把握したいときは該当箇所のソースコードを見て、それが実装された当時のプルリクエストを見て、プルリクエストのDescriptionからリンクされているプロジェクト管理ツールのチケットを見る。なんてことがよくあります。

チケットに仕様を記載する際は『この機能はなにか？』、『どのような仕様か？』、『なぜそのような仕様にしたか？』、『他に検討したが採用されなかった案（と採用されなかった理由）』などを示します。このあたりを記載しておけば過去の意思決定をトレースできるため仕様変更の際に助けになります。

『プロダクトの最新版の仕様が細部まで網羅的に書かれているドキュメント』を作る必要はないですが、個別の機能の実装時点・変更時点での仕様は調べることができるべきだと考えています。

最後に

以上、デジタルプロダクトに仕様書がいらない理由を示しました。

自社開発のプロダクトなのか、事業会社が開発会社に依頼して開発しているプロダクトなのか、チームの体制はどうなのかなど様々な判断材料はありつつも、基本的には筆者はこのように考えています。

仕様書が必要(不要)か？なぜ必要(不要)か？何をどこに書くか(書かないか)？決めるのはあなたです。