設計書よりもユーザーマニュアルを書こう！ - レベルエンター山本大のブログ

僕が今やってる例のプロジェクト*1で、 この前、設計書を作ってお客さんに確認してもらった。 分厚い設計書で、何回も社内レビューをしてもらって、 メッセージＩＤのマッピングなど細かい点をイライラしながら直して 何度も印刷して、「最終版」、「最終版２」、「本当の最終版」という お馴染みのサブディレクトリができて、 やっとの思いでお客さんに提出したんだけど、どうやらぜんぜん見てくれてないみたいだ。 しかし、一緒に提出したユーザーマニュアルには、隅々まで目を通してくれていた。 お陰で、重要な仕様の誤解を発見することが出来た。 ユーザーマニュアルはそのままHTML化されて、 システムのHELPボタンから呼び出されるから、 お客さんとしても念入りにチェックしてくれたんだ。 ところで、設計書には大きく３つの役割がある。 ・お客さんが仕様を確認するため ・エンジニアが実装するため ・保守のため 僕は今回、

[temmings]

設計書よりもユーザーマニュアルを書こう！ - 山本大＠クロノスの日記:

[northlight]

仕様化されると、要求に詰められた多くの情報が消えてしまう

[rightgo09]

激しく同意。

[katzchang]

ですよね。

[yuchi]

お客様が読める「ドキュメント」って、限られてくるんだよね。UMLはわかりやすい、だけど開発者以外はわからないよね。

[sst]

ユーザーの要件だけは、ソースからは読み取れないので設計書を見る/仕様化されると、要求に詰められた多くの情報が消えてしまうのだ

[hatest]

自分で手を動かして作らないのなら両方書こうぜ

[toriaezu]

設計書などの書類をもって「売上計上」とするところが多いからじゃないかなあ。商習慣的な意味合いが強い気がする。／社内管理資料としての設計書さえあればいいですよね

[shozzy]

「仕様化されると、要求に詰められた多くの情報が消えてしまう」　大いに同意。文脈がわからなくなると、「この仕様おかしくね？」と思っても直しにくくなる。逆に、風変わりな仕様にもちゃんと理由があったりとか。

[soyana]

【保守で必要なドキュメントは、お客様の要件がわかるもの】 【「この機能は何のために作られ、どういう使い方が想定されているか？」 それがわからなければ、保守は始まらない。】

[masakanou]

読む

[suVene]

規模によるといえば規模による。標準化ドキュメントは重要。

[pitworks]

ユーザーマニュアルの方が、機能毎の設計書よりも有効。仕様化されると要求に詰められた多くの情報が消えてしまうから // 画面遷移図も設計書にはつけるけどな・・・。

[atsuizo]

設計段階で顧客視点のマニュアル作成ができるスキルがある時点で、要件定義・設計スキルもそれなりに高いだろう。詳細仕様の書かれた資料がないとコード書けない人では設計書もマニュアルも書けまい。でもいい案。

[Itisango]

設計してる段階では作ってる側にも操作のこと全く見えないけどね。

[deeeki]

確かにマニュアルのほうが顧客には重要だと思う。納得しまくりなのですぐにでも現場に取り入れられたらいいなあ。

[islecape]

マニュアル書いて満足して終わってしまったことがしばしば……。