みんなで育てる仕様書デザイン

この記事は Goodpatch Advent Calendar 2020 の5日目です。

はじめに

開発において、仕様書はとても重要な役割を果たします。
私が仕様書を作成するときに考慮している観点を紹介します。

仕様書に求めること

正しい仕様が書かれている

本来の仕様書の目的です。
メンバーの目線を揃え、仕様を知りたいてときに知ることができ、新メンバーや未来の自分が仕様を理解できる必要があります。

属人化しない

誰が見ても正しく内容を理解できる必要があります。
誰でも書ける・読めるようにするため、エンジニアリング言語を使わず、正しい日本語で書くようにします。
エンジニア以外も仕様を書くことで、実装や運用を考慮したデザインを作ることができます。
また、現在の仕様に至るまでの過程がわかるようにしておくと、議論を蒸し返さずに納得感を得られます。

仕様書を開くコストを抑える

どれだけ素晴らしい仕様書があっても開かれないと意味がありません。
仕様書を開くコストを抑えるため、普段使っているツールに使うようにします。

仕様書作成・メンテナンスコストを抑える

仕様書は意思疎通手段であり、仕様書を作ることが目的ではありません。
なるべく低コストで作ることを目指します。
メンテナンスコストも意識し、古い仕様書はメンテナンスしなくても良い仕組みにします。

機能ごとに考える

画面ありきで考えると、本質的な課題が議論できなくなることもあります。
機能を考え、機能を書きます。

デザインとは切り離して管理する

仕様書は機能を管理し、デザインは他のツールで管理します。
また、仕様は変更せずにデザインのみ変更することが多々あり、その都度仕様書を更新するのはコストがかかります。
画面に依存する仕様がある場合は、仕様書に書きます。

履歴を書かない

履歴を見るのはコストがかかります。
履歴を見ないでも理解できるように仕様を書きます。
どうしても履歴管理が必要な場合はツールに任せます。

経緯を書く

履歴ではなく、経緯です。
例えば、「法務観点でログインをAからBに変更した」など、どうしてこの仕様になっているのか Why を書きます。

議事録的に更新する

仕様書の更新にはコストがかかります。
コストを減らすため、仕様を決めたタイミングで、同時に仕様書を更新します。
更新したら、メンバーに周知します。

概念図や箇条書きは使いすぎず、文章で書く

一般的に、図や箇条書きにすると情報量が落ちるため、基本的には文章で書きます。
文章とセットで、補足で図を書くのはとても有用です。

レビューする

仕様書をFIXさせる前に全職種がレビューし、認識のズレや仕様漏れがないかレビューします。

100%の仕様書を作ろうとしない

仕様書はあくまで手段です。
ある程度の認識ズレが発生することを許容して、ミスに気づける・カバーできる仕組みを作ったほうが、結果的に低コストになります。

階層構造で管理する

機能単位で管理します。
1つの機能が複数の画面にまたがることもあれば、複数の機能が1画面に入ることもあります。

Good

仕様書（機能単位）
｜
├共通
｜　├ライフサイクル
｜　└URLスキーム
｜　
├Version 1.0.0
｜　├新規登録機能
｜　├ログイン機能
｜　├ユーザー名変更機能
｜　└メールアドレス変更機能

Bad

仕様書（画面単位）
｜
├共通
｜　├ライフサイクル
｜　└URLスキーム
｜
├登録系
｜　├新規登録
｜　｜　├メールアドレス入力画面
｜　｜　└本人確認画面
｜　└ログイン
｜　　　├...
｜　　　
└マイページ
　　├ユーザー名変更画面
　　└メールアドレス変更画面

おすすめツール

Notion

Good

誰でも簡単に編集できます。
汎用性が高く、仕様書以外の情報も一括で管理できます。

More

リスト管理が得意ではないため、Googleスプレッドシートとの併用を推奨します。
汎用性が高すぎて自由に編集できてしまうため、運用ルールをしっかり決める必要があります。

Confluence

Good

誰でも編集できます。
汎用性が高く、仕様書以外の情報も一括で管理できます。
Atlassian系サービスとの連携が強いのも強みです。

More

編集するために編集モードに入る必要があるため、編集のための敷居が少し高めです。

Git

Good

社内サーバーで管理できるため、セキュリティ要件が高い会社でも使えます。
Markdownで書けばブラウザから簡単に見え、履歴管理もできます。

More

学習コストが高く、編集の敷居も高いです。
エンジニア職以外に普及させるのは難しいかもしれません。

仕様書テンプレート紹介

実際の仕様書は公開できませんが、簡単な仕様書テンプレートを紹介します。
プロジェクトによってカスタマイズして使えると思います。

# 概要
一行程度で機能を説明する
一行で説明できない場合は複数の機能が含まれている可能性が高いので、複数の仕様書に分割できないか考える

# 背景・目的
分析を元にした課題感と経緯を書く

# 目標
ユーザーゴールとビジネスゴールを書く
この目標を達成することが、この仕様書の目的になる

# 仕様
仕様を書く
エンジニアリング観点によりすぎず、誰でも理解できる言語で書く
議論した結果、しないと決まったことも書く

## インプット

## アウトプット

## 処理A

## 処理B

## 想定するエラー処理

## しないこと

# 実装詳細
実装時に注意する必要がある観点を書く
エンジニアリング言語で書く

# デザイン
デザインファイルへのリンクを貼る
デザイン仕様を書く

# ユビキタス言語
この仕様で新しく定義する言葉について説明を書く

# テスト
想定するテスト内容と方法を書く

# データ分析
分析観点を書く
目標を達成できたか判断できるように書く

# 参考リンク
関連する議事録等への参考リンク集

More

仕様書の作成・テスト設計の難易度が高いため、ドキュメントを書くリテラシが求められます。
反面、全員で仕様を考えるため、チームの成長にも繋がると思います。

仕様を細かく書いていないため、エンジニア間での認識ズレは発生します。
このあたりは仕様書作成にかけるコストと相談です。