【チーム開発】仕様書を書かないなら書かないで、認識合わせのためのコストは別のところで払う必要があるらしい
はじめに
対象
- プロジェクトで仕様書を書くべきか迷っているITエンジニア向け。
仕様書を書くべきか・書かないべきか
納品物に仕様書が含まれているプロジェクトではまずない疑問です。利害が発生する場合は合意事項をドキュメント化する必要もありますし、書かないという選択肢がないですね。
一方で自社の製品だと話が変わってきます。ぶっちゃけ開発者はソースコードを読んで、ローカル環境で動かせば最新が分かるので、わざわざ仕様書を見るより早いし確実ってのがあります。仕様書は古くなると平気で嘘を付くし、メンテナンスコストも馬鹿にならないし。
なもんで「仕様書なしでいこう」と決めるのは構わないのですが、仕様書なしのプロジェクトで企画・営業・運用・お客様まで含めて全員が仕様書がなくてハッピーかというと、そんなこともないケースがあります。仕様書がないことで情報共有に失敗してます。
つらつらと書いていくのですが、仕様書がないことで本来仕様書が担っていた部分を担う仕組が必要になるので、そのコストを無視して仕様書要らないと言ってるなら、大人しく仕様書を書いて共有した方が混乱はしないと思います。
無策で仕様書を失くすとどうなるか
認識合わせをする機会が減る
特に制作途中ですが、ソースコードが正とは限りません。仕様書がないということは、飛んできた要件から実装してデプロイするまでは開発者が握ることになります。その間、意図的に確認を投げない限り、確認は実装が粗方終わった後ということになります。
どうしても確認のテンポが遅れるので、手戻りが多いです。というか開発者がその負荷を担います。設計漏れや考慮漏れがあると特に大変です。情報の後出しが発生することもあります。見てみたらやっぱり違ったとか、思い出したとか。
だって細かい仕様の認識違いを詰める作業を仕様書でやってたんですから。単に仕様書だけをなくしたら、認識の齟齬が発生したままデプロイまで気付かないことは起こり得る。だからチケットや別のドキュメント、あるいはチャット経由での確認作業が必要になる。
誰も正確な仕様を知らない
「バグではなく仕様です」という内容を、バグ票として起票してくる人が一定数います。仕様を確認する前に無作法に投げてくるというのもあるのですが、プロジェクトに参加している誰もがあるべき仕様を知らない状態に陥っているということもあります。
「何が正しいか分からないなら確認してから起票しろよ」とも思うのですが、こういった場合、自分が考えている仕様こそ正しいと信じているケースも少なくありません。自分がよく知らない分野で、正しいと思ってたことが実は違ったというのは、よく観測されるケースです。
ではどこで正しい知識を学ぶかといえば、趣味であればガイドブックや入門書、研究であれば代表的な書籍があるので、それを読めばいいです。ではプロジェクトでは？そう、仕様書です。でもその仕様書は書かないことにしました。どこで正しい仕様を知ればいいのでしょうか。
共通認識・意思疎通が図れない
仕様書がないということは、用語も含めて定義が成されていない状態ということになります。仕様書があっても独自言語を用いる方もいらっしゃいますが、ともかく正しいとされる言い回しは規定される訳です。
これはTwitterで頻発するケースですが、主語が大きいあるいは用語の定義がズレていて、レスバトルが発生することは日常茶飯事です。外野の賢い人も、難癖付けられた人も状況を理解はしていますが、当の本人がこのズレに気付かずにずっと続けているという事象。
あれが業務で頻発する可能性があります。というか起きました。
共通認識を作るための前提知識の共有も、仕様書を書くためのヒアリングであったり情報収集であったりで巻き取っていたりするとですね。仕様書を書かないということは、それらに触れることもなくなるってことなんですね。参考文献や関連資料はリンクしてる筈なので。
仕様書を書かないときの工夫と考え方
適切に仕様確認を行う
もしも仕様書を通して機能の追加・改修を行ってきたのならば、その作業は別のところで巻き取る必要があります。
例えば仕様書は書かないまでも、チケットに仕様書に書くべきことを書いて確認するとか。チケットは一時的なタスクですから、仕様書のように古くなって嘘を付くということがありません。「当時はそういう仕様だった」という体で対処ができるので、メンテコストを節約できます。
チャット経由で書くのはおすすめしません。まずリンクがずっと生きている保証がない。下手をすると将来、移行と共に消えてしまう可能性があります。必ず残る場所に。
手戻りが高コストになる工程の手前で、必ずステークホルダーを交えて確認を。
自動生成ツールを使う
例えばRails案件だとデータベース仕様書がないことがめっちゃ多いです。Annotateを入れていると開発者目線不要なんですよね。関連や処理なんかもモデルを見れば済むから、わざわざ仕様書に書き起こす必要がないという。
ただこれで困るのは、営業や運用なんです。というか営業や運用がデータベースのことを把握できないがために、開発に曖昧依頼する作業が発生してカオスになる。データ抽出や調査の依頼が来るけど、似たようなカラムが沢山あって、どれのこと言ってるか謎みたいな。
データベース仕様書を出力するツールやライブラリは沢山あるので、それらを利用してER図や仕様書を出力するのが手軽です。手動更新だと、まず間違いなく更新しなくなります。
まあRailsの場合は外部キーやコメントをきちんと設定してる前提になりますけども。ガバガバマイグレーションで何も設定してないと、自動生成ツールはカラムの物理名や型くらいしか出力しないので。
勉強会・説明会の定期開催
仕様知ったる誰かの主催で勉強会や説明会を開くことも検討します。文章がない以上、どこかで正しい仕様の認識合わせをする必要がありますし、要望や改善案なども聞けるのでおすすめな方法ではあります。コストはかかりますけれど。
顔を突き合わせて話をしてみると、「あ、あの仕様ってそういう理由があったんだ」「え、知らなかった」「怪しい。認識がバラバラだ」など、意外な一面が見つかったりするものです。
大事なことですが、議事録は残しましょう。必要があれば、部分的に仕様書化しても構わないでしょう。複雑な業務フローは図に書き起こすのもありです。格式張ったものでなくてよくて、雑にホワイトボードをスクショして残しておくだけでも違います。
ここでの目的はあくまで仕様の共通認識を取ることで、仕様書のような長期的な内容の維持や、納品物としての形式を考えなくてよく、必要な作業だけ低コストで行うのが味噌。
仕様書に回帰する
ここまでの説明で、仕様書を書かないことによるデメリットやコストの方が高いと判断できる場合、潔く仕様書を書いて更新する方が結果的に良い方に転びます。
仕様確認にかかるコストや代替作業、コミュニケーションエラーによる不備への対応などなど。資料作成や会議なども含めれば、どっこいどっこいというか。証拠が残らず、言った言わないになる分、余計に面倒なことになることもあって。
恐らく多くのケースでは、大人しく仕様書を作った方が良いと思います。本質を見抜く力があるITエンジニアがいる場合は、「仕様書を書く」という作業を分解・再構築してもらうのがいいです。その際、再構築後の作業をケチるとやはり同様の問題は発生しますが。
おわりに
開発以外のメンバーも含めたチームとして動くときに、適切に情報が連携できるかという視点で見直していただくといいかと。
なんだかんだ大事なのは「事前に一言、確認があるか」だと思っていて。確認するための契機だったり、その確認先だったりが仕様書だったというのが大きそうです。この辺は単純にフルリモートにしたら失敗する話と似てますね。
要は作業の本質というか、何を目的にしていたかを理解していないと、簡単に見失ってしまうのだと考えています。作業を効率化・省力化するのは素敵な試みですが、それが同時に何を引き算してしまうか考えて、必要な部分だけ足し算しましょうって話。
Discussion