僕が今やってる例のプロジェクト*1で、
この前、設計書を作ってお客さんに確認してもらった。
分厚い設計書で、何回も社内レビューをしてもらって、
メッセージＩＤのマッピングなど細かい点をイライラしながら直して
何度も印刷して、「最終版」、「最終版２」、「本当の最終版」という
お馴染みのサブディレクトリができて、
やっとの思いでお客さんに提出したんだけど、どうやらぜんぜん見てくれてないみたいだ。
しかし、一緒に提出したユーザーマニュアルには、隅々まで目を通してくれていた。
お陰で、重要な仕様の誤解を発見することが出来た。
ユーザーマニュアルはそのままHTML化されて、
システムのHELPボタンから呼び出されるから、
お客さんとしても念入りにチェックしてくれたんだ。
ところで、設計書には大きく３つの役割がある。
・お客さんが仕様を確認するため
・エンジニアが実装するため
・保守のため
僕は今回、この３つの役割を満たすために
ユーザーマニュアルの方が、機能毎の設計書よりも有効だと感じた。
設計書に書かれた処理の手順なんてのを読んでも機能についてピンとこないが、
ユーザーマニュアルなら分かる。
なぜなら、分かるように書かなくてはならないからだ。
分かりやすくなくては、マニュアルの存在意義に関わる。
マニュアルに書くべき内容は以下のようなものだ
- そもそもこの機能の目的はこうだ。
- これをこうしたら、こうなる。
- こういうことがしたいときは、こういう風にできる。
- こういうことはしてはいけない。もしくは対応していない。
- ここの項目はあそこに影響がある。
- ここはこういうエラーがでることがある。
- こういうエラーがでるときは、こうしろ。
- などなど
最近のプログラミング環境においては、
プログラマ向けの設計書（内部設計書や詳細設計書）を書くよりも
プログラマの裁量に任せて要求を実現してもらうほうが現実的だと思う。
これはひがさんの受け売りもあるが、現場で実感することだ。
システム開発の大多数は、最初に○○設計書を作成する。顧客にレビューしてもらったり、自分たちでも内部レビューしたりするが、あれは、有効性が低い。
動かないものをいろいろレビューしても、本当のことはわからないから、レビューの結果に信憑性がないのだ。上っ面をレビューしているに過ぎない。
「設計書」の検索結果 - yvsu pron. yas
だから、設計書よりプログラムを作って動かしてお客さんに見てもらうほうが良い
というのがプログラミングファーストだと思ってる。
プログラミングファーストの考え方で行けば、実装のためには要求が分かればよい。
要求はマニュアルに現れる。
マニュアルベースにプログラム作って、動きを確認してもらえば良いじゃないか。
そうすると、設計書の最後の役割は「保守のためだけ」ということになり、
じゃあ、保守で必要なドキュメントは何か？ということになる。
僕が今いるプロジェクトは、保守チームの新規開発部隊なので、
まわりに保守チームメンバーがわんさかいる。
ためしに聞いてみた、「保守で必要なドキュメントってなんですか？」
その答えは、、、
お客様の要件がわかるものです。
ということだ。
なんと。
またもマニュアルでよいではないか。
「この機能は何のために作られ、どういう使い方が想定されているか？」
それがわからなければ、保守は始まらない。
保守を担当するエンジニアは、初期開発ばかりしているエンジニアよりも人のソースを読むスキルが高い。
ドキュメントよりもソースを信じるから、機能仕様とかメッセージ一覧とかは見ない。
（俺、苦労して設計書のメッセージIDと一覧のIDを対応付けしたのに。。。）
ただ、ユーザーの要件だけは、ソースからは読み取れないので設計書を見るが、
たいていユーザー要件は仕様化されてしまっているため、ぼんやりと類推するしかない。
これは、以前にこのブログで書いた以下の話と通じる。
つまり、仕様化されると、要求に詰められた多くの情報が消えてしまうのだ。
例えば、以下の文章を見てほしい。
「登録ボタンが押下されると、システムは確認ダイアログを表示する。」
この文章は「仕様化」されている。
しかし、この要求には、顧客の心理的な背景があるはずなんだ。
以下の３つの例で顧客の本当の要求を表してみる。
A「重要な金額データを登録する処理なので、むやみに登録してしまわないように・・・」
「登録ボタンが押下されると、システムは確認ダイアログを表示する。」
B「あまり重要なデータではないが登録処理に時間がかかるので、誤操作を避けるために・・・」
「登録ボタンが押下されると、システムは確認ダイアログを表示する。」
C「重要ではない一時データの登録処理であり、確認画面を別途用意するのも面倒なので・・・」
「登録ボタンが押下されると、システムは確認ダイアログを表示する。」
顧客の本当の要求を知れば、同じ仕様に対するプログラミングも変わってこないだろうか？
要求を知るには仕様化された設計書ではだめだ。
かといって、要件定義書なんて持ち出しても余計だめだ。
そんなものはメンテナンスの手が止まって廃れてる。
だから、マニュアルで良い。
ＣＶＳとかで履歴を管理すれば、要求の変遷も見られる。
他のドキュメントも要るものはある。
例えば、ＤＢレイアウトは必要だ
日本語のカラム名やテーブル名を調べたりするのに便利だ。
それから、標準的な動作は、マニュアルで抜け落ちることが多い。
そのため、設計標準ドキュメントは必要だ。
例えば、画面を開いたとき最初にフォーカスがあたるのはどこだとか、
横スクロールはやるべきじゃないとか、
Tabキーによるフォーカス異動は、N方向かZ方向かとか。
統一するべき動作までをマニュアルに書くと多くなりすぎる
つまり、アプリケーション全般に関わるドキュメントという奴は、
作っても利益の有るドキュメントだと思う。
そんなこんなで、マニュアルを中心に成果物を考え直すのが良いと思う。
顧客の要求を120%実現するために、最低限の労力でやる。
これぞ設計者の誇りだ〜〜！
