システム開発の受託開発は、納品物としてドキュメントを求められることが多いですが、どこまでのドキュメントを書く必要があるか、はクライアントと開発チームによって異なります。
今回はその判断基準を考えてみたいと思います。
この記事をオススメしたい方
● これからシステム開発を行おうとしている方
● 納品物の判断に悩んでいる方
ドキュメントは多い方が良いのか、少ない方が良いのか？
発注側の立場ではドキュメントは多ければ多い方がよいと感じる方が多いかと思いますがこれは良い点と悪い点があります。また誰向けのドキュメントかという目的を明確にする必要があります。
＜ドキュメントが少ないことのデメリット＞
✓ 必要な情報がわからない
と考えてしまいがちですが、エンジニアであればドキュメントを把握するより実装のソースコードを読むほうが早いです（実装がシンプルにわかりやすく書かれていることが前提です）。またビジネスサイドの方は、自分たちが分かるレベルの情報でのドキュメントが存在していれば問題なく、量に依存しません。
基本的に、1社で開発を行いその会社が運用も継続する場合は、最低限のドキュメントにする方がよいと考えます。
＜ ドキュメントが少ないことのメリット＞
✓ 大量のドキュメントを読み込むのに時間がかからない
✓ ドキュメントを作り込むより、システム自体をわかりやすくすることに時間を使える
✓ どこに何が書かれているか見つからないというケースが減る
✓ 仕様変更の際など、ドキュメントの更新の手間が減る
端的にまとまったドキュメントは少量で仕様を早く理解でき、メリットが圧倒的に多いです。
ドキュメントは何で管理すべきか？
必要最低限のドキュメントは、運用も大切です。
＜システム開発におけるドキュメントのトラブル＞
✓ 最新版がどれか分からない、バージョン管理がされていない
✓ 同じ名前や同じような内容のドキュメントが複数存在する
✓ 適切に更新されず、最新版になっていない
これらが起こると、ドキュメントの信頼性が低くなり結果開発チームがドキュメントを見なくなってしまいます。
当面はそれでもよいかもしれませんが、担当者が変わることや他のチームに引き継ぐことになった際に、いざドキュメントを用意するとなると大変な工数が発生します。
ドキュメントは常に最新版で、どこになにがあるかを全員が理解出来、見れば分かる状態にしておく必要があります。
＜ ドキュメントの管理方法＞
✓ Googledrive・github・swaggerで管理する
✓ 常に同じファイルを更新し、不要なものはアーカイブする
✓ ドキュメントが複数に分かれることなく、少ないファイル数で管理する
✓ 以前のバージョンが見たい場合は、1つのファイルの履歴を遡る
✓ 今の開発チームでどういうドキュメントが存在しているかをwikiで管理する
これらの管理方針をチーム全員が理解して運用することが重要になります。
どんなドキュメントが必要か？
必要最低限のドキュメントという意味では以下が上げられます。
＜最低限必要なドキュメント＞
仕様
✓ 画面設計書（デザインと機能説明含む）
✓ 機能/画面一覧（画面名称・URL構造含む）
✓ メールやプッシュ通知の一覧と詳細
✓ フロー図
システム
✓ ER図
✓ シーケンス図
✓ テーブル定義
✓ APIドキュメント（swagger）
インフラ
✓ デプロイ手順・構成図
✓ 非機能要件
✓ サーバー構築手順・構成図
＜ケースによって必要なドキュメント＞
✓ 体制図
✓ 単体テスト/結合テスト仕様書・結果
✓ バージョン管理方法
✓ ローカル環境構築手順
またドキュメントを書くツールの選定は開発チームのメンバーにも依存してきます。ドキュメントの目的がビジネスサイド向けの場合は、テキストのドキュメントよりもPower Pointを活用した絵で見て理解できるドキュメントの方が良いと思います。
一方でSIer出身のエンジニアの方は、絵のドキュメントに慣れていない方もいらっしゃいますが、これからはテキストよりも少ない情報量で理解できる絵の方がメリットが大きいと思います。
まれに「ユーザーの画面操作方法をドキュメントにしたい」という声を聞くこともありますが、画面のUI/UXや「よくある質問（wiki）」が整っていれば、本来必要ないとご提案しています。
それでもユーザーのリテラシー次第では、ドキュメントで保管するのではなく操作動画やリアルイベントを実施するほうが効果が高くなっています。
一番重要なのは、わかりやすい設計と機能構成
システム開発は作った人の思想や思考が現れやすいものです。システム自体がシンプルでわかりやすければ、作りも自ずとシンプルになり、たくさんのドキュメントを見なくても理解できやすくなります。
そのためには、初動の設計に熟練した設計者をアサインし、わかりやすい機能にまとめていくことが大きな分かれ道になります。
設計がスムーズに進めば進むほど、ドキュメントも手戻りが少なくなり、ツギハギが減るため設計書のクオリティも上がっていきます。
システム開発に必要なドキュメント、いかがでしたか？
Good Thingsでは、システム開発の設計から実装までを得意としたメンバーで構成されています。
