なぜかこんな幻想があります。
ドキュメントは正確無比で、全てが網羅されていなければならない
はい、残念!そんなドキュメント無理ですから!
その結果として、ECサイトのショッピングカートへの商品追加処理といった機能のドキュメントが次のようになります。
ユーザが該当商品において「ショッピングカートへ追加する」ボタンをクリックした場合、該当商品をユーザのショッピンカートデータに追加する。その際、商品マスタより該当商品のデータを取得し、現在在庫数から注文希望商品数が引き当て可能であるか判定する。もし現在在庫数が注文希望商品数を下回っていた場合、商品詳細画面へリダイレクト処理を行い、「在庫がありません」というエラーメッセージを赤文字で表示する。注文希望商品数が現在在庫数を下回っていた、または同一であった場合は…
はっきり言って人には読めない文章ができあがります。こんなの読んで理解できるとすれば、それは人間じゃないんじゃないかと思うほどです。書いても読まれない、十分に理解が進まない文書は絶対に書いてはいけません。はっきり言ってムダです。
しかも上記の内容には不備があります。
- ボタンのラベルがショッピングカートへ追加するではなくなった場合
- ユーザの定義。未ログインやまだ購入したことのない利用者の場合ユーザと定義していいのか
- ショッピングカートにある注文情報を考慮していないので在庫引き当て判定が問題あり
- 在庫がありません、でいいのか
- 一覧ページから注文できる仕組みにした場合、エラーのリダイレクトが商品詳細画面でいいのか
などなど。細かく書けば書くほど、不備が目立ったり、ドキュメントがバグの温床になる可能性が高くなります。
それを防ぐためには人が読んで十分理解できるレベルであるのが大事です。例えば以下のような感じでしょうか。
お客さんが商品をショッピンカートに追加できるようにします。在庫が足りなかったらエラーを出してください。
後の足りない部分についてはプロダクトマスターに確認して詰めれば良いでしょう。まず読めて、何がしたいのかを把握できる内容であることを優先すべきです。
なおこれはアジャイルな場合なので、オフショアの場合は異なるので注意が必要ですよ。