仕様書をどこまで細かく書きますか？
インフラの業務をやっていると仕様書を書く機会が多いです。基本設計書、詳細設計書、運用設計書・・・・等々。しかも、プロジェクトによって基本設計書を概要設計書と言ってみたり、詳細設計書を機能設計書と言ってみたりと、呼び方が違うこともよくあります。
このような設計書の区分は、どこかの書籍に書かれていたとか、何かの手法で説かれている呼び方なのでしょうか。もう少し違う分け方があってもいいような気がします。開発手法に詳しいわけでもないですが、時代とともに移り変わる開発手法にあわせて、仕様書の書き方、区分のしかたは変わっていくものです。
実際に作業していても、その記述が役に立ったか。こういうことを書いておけばよかったとか、内容に変化があってもいいような気がします。また、使用する機器やソフトも時代とともに変化しています。当然、仕様書の書き方や内容も変わってくるはずです。ただ詳しく書けば何かの役に立つというものでもありません。
要件をまとめたり、どのパラメータを割り振るかをはっきりしないままで詳しくドキュメントを書こうとすると、決まって莫大な工数がかかってしまいます。詳しく書こうとするより、事前のきめごとをはっきりしておく方が、良い成果物が期待できそうです。むしろ、無理に詳しく書こうとしたり、語彙にまで正確さを過剰にもとめると、簡単に工数を食い潰してしまいます。
仕様書をいくら細かく、正確に書こうとしても何も変わりません。必要なのは、書かれた内容をどれだけ読んだか、考えたか。そして、それを元に工夫したかです。業務に割り当てられる時間も無限ではありません。何を書いて何を残すか。これは過去書いたドキュメントを読み直して、ドキュメントの書き方を考えてみてはどうでしょうか。きっと、あなたに大きな利益があると思います。
コメント
天狗の下駄
仕様書設計書に限らず、「過去の成果物を読んでみる」ことで重要なのは、読んでみて同じものを作ることができるか、出来ないのであればどんな記述が足りないのか、これを考察できるようになることですね。
ぶっちゃけ、自分が組んだアプリやスクリプトのコードですら、コメントと言う仕様を明確に残しておかないと、完成後半年程度で「あれ？ここのコード何やってるんだっけ？」になるぐらい、人間の記憶力とは脆いものですから。(歳を取ると「倍率ドン！さらに倍！」になりますし)
因みに、(公官庁の指導が厳しい)業界によってはドキュメントの書式(インデント、フォント、行間等)も整っていないと、レビューではねられることもあります。
匿名
例のあの人リスペクトしてるのはわかったから、いい加減アイコン変えてほしい
邪魔でしょうがない
Horus
> 天狗の下駄 さん
コメントありがとうございます。
> 因みに、(公官庁の指導が厳しい)業界によってはドキュメントの書式(インデント、フォント、行間等)も整っていないと、レビューではねられることもあります。
これ、よく分かります。私もこういう事案に遭遇して「えー。」となったことが幾度かあります。
Horus
> 匿名さん
例のあの人のファンですかね。だとしたら通じる部分もあるのでちょっと残念です。ただ、例のあの人ならきっとこう言うでしょう。
「だったらもう二度と来るな。」
そこまで言う気はないですが、匿名で「邪魔」とぼやき逃げするのはかっこが悪いと思います。
てんるう
>> 因みに、(公官庁の指導が厳しい)業界によってはドキュメントの書式(インデント、フォント、行間等)も整っていないと、レビューではねられることもあります。
>これ、よく分かります。私もこういう事案に遭遇して「えー。」となったことが幾度かあります
ドキュメントを使う側になった時に、この辺の重要さが分かります。
急にフォントやインデント（あと文字サイズ）が変わると、その部分に何か意味があるのかとか考えてしまうんですよ。
なので私の場合、エンドユーザーさんよりも、5年後のリプレースの時とかに同業他社のエンジニアさんが読む事を想定して、きっちり書くように心がけています。
Horus
> てんるう さん
＞ ドキュメントを使う側になった時に、この辺の重要さが分かります。
なるほど。コメントを頂きはっとしました。
キチンと正確にドキュメントを書くのは重要なんだなぁと。
ただ、そこまで重要なものだったら、もっと手法がいろいろと考え出されてもいいように思いました。おもしろいテーマなので、機会があればコラムで書かさせて頂こうと思います。
天狗の下駄
どうも私の挙げた業界云々の例えの意図が上手く伝えきれていなかったようなので、今更ながらに補足しておくと、
別に一文、一章単位で書式を揃えなければ云々と言う意味ではありません、そのレベルであればどの業界でも指摘されて当然です。
業界云々で意図していたのは、要件定義書から設計書、作業手順書、試験仕様書、運用手順書に至るまで、書式が決められている(テンプレート通りじゃなきゃ承認されない)ことや、下手をするとその決められた書式と言うのが、一文中の書式に乱れがあることが往々にしてある、と言った根本的な部分での「なんじゃこれ？」なネタです。
因みに、私もドキュメントを作成するときには相応に心がけて、注意すべき点や協調すべき個所では、「あからさま」にフォントの種類やサイズ、色(濃淡)を変えて、ドキュメントの使用者が不要に考え込む必要がない方法をとっていました。(たまに「やりすぎ」ってツッコミ入りましたが。