納品物件としての、設計書類

受注開発稼業、
納品はプログラムだけじゃなくて文書も必要です。

「ドキュメント」という単語は一般名詞ですが、
この業界で言えば、設計書類の事を指す。らしいです。

20年ぐらい前までは、ドキュメントの厚さで、
受注金額が決まるという良く判らない風潮がありました。
作った方からすれば、ある程度の達成感がありますが、
受け取った側はそれを使うかって言ったら使わないです。

ウォーターフォール型の、古典的開発スタイルは、
最初の設計書類と、後期のプログラム実装とでは、必ず乖離があります。
なぜって、修正が面倒臭いから。

故に、納品後で、「別人」が修正しなければならない場合はままあります。

契約方法にもよりますが、ソース付きで納品してしまったら、

それは納品先でも修正できてしまうので、

わざわざ発注するより、自前でやっちまえ、というのは正しいです。

その場合でも、プログラムに付いてきたであろうドキュメントは使いません。
そもそも、大量のドキュメントを受け取っても途方に暮れるだけです。
実際、途方に暮れました(実体験)

仮に読んだとしても何のこっちゃ判りません。
4.5次元の「仕様」を、2次元未満の文書に落とす訳ですから

自分の期待している「次元」でなければ、推理小説読むようなもんです。

有る程度の熟練者なら、プログラムを読んでしまった方が早い。

そして、その別人の修正によって、
さらにドキュメントとプログラムでの乖離が大きくなります。

なぜそんな事が起こるのか？

理由は簡単です。
ドキュメントに細かい事まで書きすぎたからです。。

関数名とか引数の意味ぐらいまでなら、まだ良いのですが、

関数内部のフローチャートとか描いちゃったらもうダメです。
変数名とかの話をせざるを得なくなる。乖離の危険が大幅アップ。

そもそもフローチャートを書こうというのは、
プログラムの修正コストが、非常に高価だった時代の名残り。

ディスプレイもキーボードも無かった時代。

• パンチカードだの、
• 紙に書いてパンチャーに渡すだの。
• 順番待ちだの。

黙って待ってる訳にもいかないので、紙と脳みそでデバッグするしか無かったのです。

昔話です。筆者は伝説でしか知りません。

フローチャートが全面的に要らない。とは言いません。
製作者が、思考を整理するためには非常に有効です。
ただし、納品物件としては、要らないんじゃね？と思う。

20年前ぐらいまではまだ良かった。予算はあったので。

ところが21世紀になってみたら
物件自体が、小規模化＆短期化＆低予算化してますので、
ドキュメントを書く時間すら惜しかったりします。

本当に細かい話は、ソースを読んでしまった方が確実です。

そして、納品物件としてのドキュメントは、

オヤクソクではなく、目的を考えるなら、

ソースを「補間するモノ」でなければなりません。

要件定義だけはすり合わせる必要がありますが、

クライアントの想像力が豊富でないと、大抵何の話か通じません。
結局、修正せざるを得なくなります。
じゃあもう作ったの見せちゃった方が早くね？

それでも依然として、「COBOLで慣らした」感じの方々は

エクセルで罫線を作り込んだフォーマットを持ってきて

そこに文章を入れたくて仕方ないらしい。

「帳票」って奴ですね。

エクセルやらワードやらを、

結局「清書ツール」としか使ってないので

運用は、「紙文書」を逸脱して居ません。

ということに気づいているのか居ないのか？

それはそれで問題があるのですが、それは別の機会に。