前提
- 内部だけで見ることを目的とした機能仕様書を模索した結果です。クライアントへの納品義務などがある場合はあまり参考にならないかも...
- 今回あくまで私が今のチームに適した形として結論を出した機能仕様書に関しての記事になります。1意見として流し見してもらえればなと思います。
- プロジェクトチームメンバーが少ない&ほぼ若年層のチーム向けの仕様書との向き合い方を考えた記事です。
結論
「過程はいいから結論の形をくれ！！」って思う人もいるかなと思うので
先に結論から！
- 完璧な仕様書を求めすぎると逆に誰も書いてくれない
- 仕様書の情報のみでコードの流れ8割理解できるものであれば合格点にする
- 機能仕様書を書くということは開発を楽にすることってことを認識してもらう
以上を踏まえて↓のフォーマットが今のチームにとってベストな仕様書の形だなとなりました！
参考になるかわからないけどテンプレート置いておきます。
# シーケンス図
(ここにmermaid.jsでかいたシーケンス図が入る)
# リクエストパラメーター
param名 | 型 | table名 | column名 | 備考
------ | ------ | ------ | ------ | ------
xxxxxx | xxxxxx | xxxxxx | xxxxxx | xxxxxx
# レスポンスパラメーター
param名 | 型 | table名 | column名 | 備考
------ | ------ | ------ | ------ | ------
xxxxxx | xxxxxx | xxxxxx | xxxxxx | xxxxxx
# バリデーション項目
(バリデーションチェック項目とNGの場合のメッセージなどを書く)
# 備考
(何か特記事項や特別な業務ロジックについての解説があれば書く)
過程
今年5月に今の会社に転職しまして、現在のプロジェクトに入りました。
当時メンバーが
PM: 1名
SE: 私
PG: 2名
って感じでした。
アサイン時に色々案件説明をPMの方にしていただく中でこういう会話がありました。
PM: 「何か質問ありますか?」
私: 「設計書などのドキュメントってどこで見れますか?」
PM: 「....ないです。」
.......なるほど????
ここから私とドキュメントとの戦いが始まりました。
とりあえず、ないままで進み続けるのはデメリットの方が多いし、
何よりメンバーが増えるたびに不便すぎるなと思い、
まずは、機能仕様書を書き進めることにしました。
当時のフォーマットはざっくりこんな感じ
# シーケンス図
(ここにmermaid.jsでかいたシーケンス図が入る)
# 機能詳細
(シーケンス図の内容+シーケンス図で書ききれなかった詳細な条件)
# リクエストパラメーター
param名 | 型 | table名 | column名 | 備考
------ | ------ | ------ | ------ | ------
xxxxxx | xxxxxx | xxxxxx | xxxxxx | xxxxxx
# レスポンスパラメーター
param名 | 型 | table名 | column名 | 備考
------ | ------ | ------ | ------ | ------
xxxxxx | xxxxxx | xxxxxx | xxxxxx | xxxxxx
# バリデーション項目
(バリデーションチェック項目とNGの場合のメッセージなどを書く)
# 備考
(何か特記事項や特別な業務ロジックについての解説があれば書く)
上記をPM・メンバーに共有してそのまま書き進めることになったのですが...
- 仕様書作成+開発で作業時間が増える
- 課題消化数が減ってくる
- 改修課題が溜まり始める
- 1つ1つの課題リリース期限が短くなる
- 開発するのでいっぱいいっぱいになってくる
- 仕様書書かなきゃいけないけど余裕がなくなって、作成途中で放置され始める
- 作成されなくなる
😭😭😭😭😭😭
当時私の中で「機能仕様書は絶対書くもの」って感じだったので
正直なんで書いてくれないんだろうって本気で悩みました....
なんなら誰も書いてくれないなら一人で書いてってやるって意地にもなってました。
なんとかやってはいたものの、全部の機能仕様書をメンテしながら他のドキュメントも作成し、自分の課題を消化しないといけない。
割と地獄でした。
ちょっとこれはこのまま進むと私だけしんどいし、「機能仕様書を書く」ってことが定着しない気がする。
なんで書かなくなるのかなあってめちゃくちゃ考えて、思い当たることがありました。
それは
「機能仕様書を書くことに時間がかかることが開発者の負担になっている」
「機能仕様書を書くことに対するメリットが感じられてない」
ってことでした。
私の中で「機能仕様書は書くべきもの」って前提があったので
「負担」に感じたり、「メリットデメリット」を求める対象じゃなかったんです。
そこで、どうやったら「負担」に感じることなく、
「メリット」を実感してもらえるか考えました。
最初に、「負担をなくす」ことから対策を打ってみました。
実は割とすぐ結論が出て、
「今の機能仕様書が負担 = 量が減れば負担少なくなる」
って単純に思ったんです。
なので、試しに一番レビューする上で指摘が多かった「機能詳細」を無くしてみました。
次に、「メリットを感じる」ことについて対策を打とうと思いました。
真っ先に思い浮かんだのが、機能仕様書を書くことを教えてくれた先輩の言葉でした。
「機能仕様書は開発するための説明書。説明書がないと何を作るのも大変でしょ？」
こ・れ・だ！
そこである課題でPGメンバーに
改善した機能仕様書を書いてもらってからそれを見ながら、開発を進めてもらいました。
メンバーからは「機能仕様書書いてから実装するの楽ですね！」
ってありがたい言葉をいただきました。
メリットを感じてもらってからは、
積極的に機能仕様書(なんなら他のドキュメントも!)書いてくれるし、事前に機能仕様書で仕様が掴み切れるから
単純に品質が上がるさらなるメリットまでついてきました。
そうして今では
「ドキュメントを書いてから開発する」が
プロジェクト内で定着することに成功しました！！！！
やったああああああああ！！！！
まとめ
今回初めてこういう記事を書いてみたんですけど、
全体的にだいぶ長くなっちゃっいました....反省....。
結論については上の「結論」に書いた通りで、
何事も「潔癖」になりすぎるとだめなんだなーって身をもって体験しました。
今回は「機能仕様書」のことしか触れませんでしたが、
他にも色々ドキュメント整備を進めててこの辺もいつか記事にできたらいいなーって思ってます。
最後になりますがこの記事を読んでくださった方々
本当にありがとうございます。
この記事が誰かの役に立ったらいいなー!