何のためにドキュメントを作成するのか
現在担当している案件の基本設計書案(アウトライン)を作成してみたので上司に添削していただいたのだが、散々な結果に終わってしまった。
上司が言ったことと同じことを書いているサイトを見つけたので引用しておく。
しかし,型通りに作った設計書が,常に目的にかなった“正しいもの”であるとは限らない。一番怖いのは,「設計書は何のために存在しているのか」という点を設計者がうっかり忘れているか,そもそも意識していない場合である。
意図が伝わる設計書作成の心得【第1回】 | 日経 xTECH(クロステック)
設計書を作成する上で,標準化や定型化にとらわれ過ぎてしまうと,設計書を「何のために作るのか」という根本的かつ重要な情報が抜け落ちやすくなる。「とりあえず標準に沿って作成すればよい」という設計者の態度は,後の工程でトラブルを生む原因になりかねない。
意図が伝わる設計書作成の心得【第1回】 | 日経 xTECH(クロステック)
また、実装を外部の方にお願いするかもしれないので、設計書を渡して開発がお願いできる内容にまとめて欲しいとのこと。そのためには次のようなことを意識するといいらしい。
- これだけ決まっていれば開発できる
- 質問されたときに答えられない部分がないか
- 読む人の立場になる
現実的な話として以下も大切とのこと。
- 細かく書きすぎない
- 省略出来る部分は省略する
【追記】
基本設計書の案はオリジナルではなく、これまでの案件で見てきたものをベースに作成したから、散々な結果になると思ってなかっただけにちょっとショック。
これまで見てきた設計書の多くは体裁と枚数ばかりにこだわったものだったため、「そんな設計書の書き方を覚えるんじゃなくて、もっとみんなのためになる設計書の書き方を覚えようよ」ってことが言いたかったんだろなぁと。