📕

システム開発で設計書がないあるあるを回避できるか

2022/03/09に公開

ツール

特に顕著なのがアジャイルですかね。
『アジャイルなんでドキュメントを作らない』ってよく聞くのは。
実際は作る時間がないとか、作れないが大きな理由な気がしてます。
しかし、どんな開発においても最低限のドキュメントは必要だと思うんですよ。

スキルや経験があれば『ソースコード読め』『ソースコードが正』『今ある動作しているシステムが仕様』で、まかり通りますがそうでないと探す時間やら、学習コストが・・・（笑）

ということで、テスト・開発それぞれの視点での気持ちを簡単に挙げたうえで、
システム設計書は、このくらいはどうでしょう？という提案が結論となってます。

開発・テスト（投稿者）の気持ち

テスト部隊視点

第3者検証を実施するテスト部隊の多くは、ソースコードは読めないし読まない前提でいるべきでしょう。
なので、テスト設計をするためのインプットは、『設計書』になります。
【今あるシステムが仕様】はバグも含めて仕様になるので、よろしくなく。
そのバグをおかしいというためには経験や直観力が必要になります。

もっというと、テスト設計においての期待値は明確である必要があるのです。

開発部隊視点

一方で開発部隊は要件定義、設計・実装・単体テストなどやることが多い中で、設計書にフィードバックすることの優先度が下がりがち。というのも理解できます。

ここで語ることでもないですが、安直にいうとやらない勇気が必要な気がしてます。
ちなみに、なんでもかんでも全部やらないってわけではなく、関係者各位と調整のうえここまではやります。
など範囲をハッキリ明確にすることです。

課題感

そもそも設計書が存在しない
設計書の粒度・内容（書きすぎ/書かなすぎ）
設計書の種類（画面遷移図など）
設計書をどのアプリで作成するか
バージョン管理
設計工程完了後のフィードバック
チームメンバーなどとの認識齟齬

上記のような課題感かなと考えており、今回はその中でも
『そもそも設計書が存在しない』は総合的な問題として・・・。

『設計書の粒度』、『設計書の種類』と
『設計書をどのアプリで作成するか』、『バージョン管理』をピックアップしようと思います。
プラスで『設計工程完了後のフィードバック』が関連してきますかね。

設計書の種類・粒度（内容）

設計書の切り分け

必要であろうと考える設計書を種類を列挙しMoSCoW分析にて重要度付けを行いました。
さらに設計書の内容についても同様に重要度付けを行いました。

MoSCoW分析定義

MoSCoW	説明
Must	必須の要件。満たせない場合には、認識齟齬が生じる
Should	満たせないと影響が大きい要件。対応要否の影響を考慮して対応可否判断が必要な要件
Could	できれば対応したい要件。コストやリソースによっては対応を見送ってもよい要件
Won‘t	対応不要な要件。将来的なものとして先送りしても問題ない要件

まとめたリスト

作成するアプリ・バージョン管理

設計書を作成するのはMS系のアプリケーションが優秀ですよね。
しかしながら、バージョン管理が課題になりがちです。
（所属先でOffice365とか使っていれば別ですけど。）

なので、同じファイルを編集する（共同編集）ことで、チームメンバーが管理するファイルが煩雑になりにくくなるのかなと考えています。
ローカルファイルが最新を防止したいですし（笑）

バックエンド
OpenAPI（Swagger）や『.md(Markdown)』を使用する
※厳密にいえば共同編集ではないのですが、実態としてはテキストファイルなのでソースコードと一緒にバージョン管理してしまうのがいいと思ってます
フロントエンド
画面定義などは、Notionやスプレッドシートがよいかと思います。
Office365使っていれば、Teamsやらで共同編集可能です。
ワイヤーはXDですかね？（XD使ったことないですが・・・共同編集できたような）
その他
フローは最近draw.ioを使っています。フリーですし、エクスポートしたらバージョン管理に乗せられるので。

ただ、受託案件だと納品物として設計書を納品するでしょうから、
一概に絞れるものでもないのが現状だと思います。

設計書の種類・内容などの方向性は、しっかり先方とすり合わせを行ってFixさせてくださいね。（命を守る観点で大事）

あとがき

設計書の内容やらで考えることが多く、自分の考えをまとめたいと思っていたのが本記事の背景です。
改めて表をみると『Must』が多いように思えますね。
『Must』を減らして気持ちを楽にするとしたら、開発側で必要なドキュメントか、テスト側で必要なドキュメントかでしょうか。

ですがそれはあまり意味がないので・・・。

ドキュメントの記載粒度は、『10人中7、8人』が同じ解釈になれば、
程よい粒度なんじゃないかと考えたりしてます。
あとは内容的に齟齬が発生しやすいと思われる振る舞いなどがあれば、そこを重点的に記載することを意識しています。
『Must』の内容はエンジニアが【苦】にならない粒度感ということが重要だと考えています。

それに伴ってテスト部隊は設計書を読む努力をしたほうがいいでしょうね。

あとは、バッチはどう作っていくかは、模索中です。
何かよいツールなどがあれば教えていただきたいです。