いい加減な仕様書や設計書なら無いほうがマシ

高木です。おはようございます。

最初に断っておかなければならないのは、私はドキュメントを書くのが嫌いなわけではありません。
とりわけ文章については、これだけブログ投稿を繰り返していたり、何冊も書籍を書いたりしていることからもわかるように、どちらかといえば好きなほうです。
私が嫌いなのは、無意味なドキュメントを書くことです。

私が関わっている仕事では、まともな仕様書や設計書はないことがほとんどです。

仕様書に関しては、事務方の承認を得るために形式的なものを作成する程度です。
設計書に至ってはほとんど書くことがありません。

では、どのように開発を進めるかというと、紙やホワイトボードなどに落書きをしながら方向性を定め、以後は直接コードを書きます。
ワープロで設計書を書く暇があるなら、直接コードを書くほうが手間が省けるというものです。

ドキュメントの整合性をチェックするツールというのは見たことがありません。
なので、人力で校正するしかありません。
ましてや、そこに書かれた内容をもとにコードを書いて、正しく動くかどうかを担保する方法などありません。

一方、コードであれば、コンパイラや静的解析ツールなど、整合性その他をチェックするツールがいろいろあります。
実際に動かして確認することもできます。
同じ手間をかけるなら、コードのほうがクオリティが高いものができるのは当然なのです。

それに、仕様書とか設計書とかを「書きました」といって渡してくれるのはいいのですが、いい加減なものが多すぎるのが現実です。
とくに、細部まで書き込まれた設計書であれば、実装時には当然その内容にしばられるわけですが、そもそもがいい加減なので、まともなコードが書けなくなります。

さらにいえば、細部まで書かれた設計書は、書いてある内容だけでなく、書かれていない内容も同じぐらい意味を持ってきます。

それぐらい細かいところまで書くのであれば、当然記述すべき内容というものがあります。
もし、そうした内容が書かれていなかったらどうでしょう。
それは、あえて対応しない、あるいは省略するという意図を意味するのではないでしょうか?
まさか、怠慢で書いていないなどということはあり得ないはずですから(もしそうなら、それは設計バグです)。

詳細設計書のたぐいは、コーディングするのと同じかそれ以上に慎重に記述すべきものなのです。
しかも、ツールの支援がない状況で記述しなければならないのです。

そんな過酷な条件のもと、生み出された仕様書や設計書のたぐいは、いい加減なものであれば百害あって一利なしです。
いっそ何もないほうが作りやすいというものです。

私は、体裁を整えるためだけの無意味なドキュメント作りのような非効率なことに時間を費やしている暇はありません。
それに、私が設計するときは、日本語ではなく、直接プログラミング言語で考えます。
ドキュメントから入るのは、その思考の流れを遮る効果しかありません。

たとえていえば、絵を描くのに、先に日本語でどんな絵にするかの「設計書」を書いてから筆をとるようなものです。
作曲をするのに、先に日本語でどんな曲にするかの「設計書」を書いてから楽譜を書くようなものです。
考えただけでも苦痛でしかありません。

世の中にはワープロ打ちが得意な人材は豊富にいるようです。
形式を整えるためだけのドキュメント作りはそうした人たちにまかせて、私は純粋に設計のほうに注力したいと思います。