ケイーゴ・K / PIXTA(ピクスタ)
開発部の齋藤です。
最近、技術的負債を返済するタスクがあり、その中に仕様書が残っていない機能、いわゆる「コードが仕様書」である機能もありました。 それらの機能を改善する際、そもそもどのような動作が正しいかわからず、システムから推測したり、他部署や社歴の長い人にリスニングをしたり、確認に手間取りました。 そこで、この記事では、最低限どのような仕様書を残すべきであるかを記述します。 仕様書は残したいけど時間がない人や、私と同様に仕様書がなく過去に痛い目にあった人に読んでいただければと考えてます。
背景
スタートアップ企業の場合、リリース優先で仕様書を残すことは少ないと思います。 より良い機能をより早くユーザに提供しなければ、サービス自体が終わってしまう可能性もあるため、仕方がないことだと思います。 ただ、リリース優先だとしても、技術仕様書は後回しするとしても、機能仕様書については残しておくべきだと考えています。
技術仕様書と機能仕様書について
機能仕様書について、Joel Spolsky氏はJoel on Softwareの「やさしい仕様書」という記事で以下のように定義しています。
機能仕様書は、ユーザの観点から製品がどのように動くか記述する。 それはどのように実装されるかは問題にしない。 それは機能を話題としており、画面とか、メニューとか、ダイアログとかいったものの仕様を定める。
また、技術仕様書についても以下のように定義します。
技術仕様書は、プログラムの内部の実装について記述する。 それはデータ構造、関係データベースモデル、プログラミング言語や開発ツールの選択、アルゴリズムといったものを話題としている。
技術仕様書については、稼働しているシステムの技術を調査すれば、なにを利用しているかはわかるので、技術仕様書は作成することができます。 また、なぜ選択したかについても、システムから推測することはできます。 そのため、技術仕様書はあったほうがもちろん良いですが、後回しにしても問題ありません。
ただし、機能仕様書については、稼働しているシステムの機能を調査しても、どのように動作しているかはわかりますが、その動作が正しい状態かわかりません。 また、なぜその動作にしたのかはシステムからは知りようがありません。 そのため、稼働しているシステムから推測が難しいので、機能仕様書を残すことは重要です。
機能仕様書の残し方
だれでもわかるように書く
機能仕様書は技術仕様書と違い、機械に対して何をするかではなく、人間に対してどのような機能なのかを説明する仕様書です。 そのため、自分の専門分野以外のメンバーが読んでもわかる仕様書を残しましょう。 自分以外の機能実装に関わった人に査読してもらい、理解できるかを確認するとよいです。
遅くてもリリース前には書く
機能を実装する前に、機能仕様書を書くべきですが、実験的に機能を実装することもあると思います。 そのため、機能のリリースが決まったときには、リソースをとって機能仕様書を記載しましょう。 チケット管理しているのであれば、機能仕様書作成済みかどうかの確認を完了条件に入れるとよいです。
機能ごとに責任者を決めて書く
機能ごとに機能仕様書は１つだけ存在していて、機能が更新されるときに機能仕様書は更新される必要があります。 機能仕様書が複数あったり、最新に更新されていない状態が続く場合、仕様書の信頼性がなくなります。 そのため、機能ごとに機能仕様書を管理する責任者を決めましょう。 立場にかかわらず、機能開発に関わったメンバーのひとりを責任者に指名するとよいです。
機能仕様書があることのメリット
機能の不具合修正や拡張が早くなる
どのように動作するのが正しいかわからない機能に対して、不具合修正や、拡張を行うことがあります。 その際は、毎回コードを読んだり、他部署や社歴の長い人にリスニングして、どのような動作が正しいか調査をしていました。 機能仕様書があれば正しい動作を調査する必要なく、不具合修正や拡張を早く行えます。
他部署とのコミュニケーションコストが減る
ユーザや他部署から、この機能はどのように動作するのが正しいか聞かれることがあります。 その際も、毎回コードを読んだり、他部署や社歴の長い人にリスニングして、どのような動作が正しいか調査をしていました。 機能仕様書があれば、「この仕様書に書いてあることが全てです。」で済ますことができ、コミュニケーションコストを削減できます。
引き継ぎ内容が明確になる
メンバーがプロジェクトやチームから抜ける時に、何を引き継げば良いのかがわからないことがあります。 その際は、抜けるときに残す情報を決めたり、抜けるメンバーの判断で、情報を残したりすることしかできませんでした。 機能仕様書の責任者を決めておくことで、引き継がなければいけない機能が明確になります。
最後に
私のチームでは最近、仕様書が残っていない機能の不具合対応や修正をした場合、機能仕様書を書くことがチケット完了の条件に含まれるようになりました。 これを続けていくことができれば、「コードが仕様書」の状態から脱却できるではないかな、と思っています。
ピクスタでは、機能仕様書を残すことにも理解があるエンジニアを募集しています。
