もっと詳しいドキュメントの前に、技術力足りてますか？

このところ製品が好調ですが、当社ではお客さんからの要望にお応えするべく、受託開発も行っています。

受託開発というと、当然プログラムのソースコードや実行ファイルのような成果物の他に、
「ドキュメント」を提出する場合がほとんどでしょう。

ドキュメントは、どのような外部I/Fを持っていて、どのように他のシステムと連携するか、
どのような設計思想で、どのようなモジュール構成となっているかなどを知るための非常に重要なものです。

とは言う物の、私はドキュメント書きは苦手なので、出来ることならあまり書きたくないのですが、
求められる最低限は提出しているつもりです。

しかし、中にはドキュメントの量が少ないと怒られてしまうこともあります・・・
「この程度の内容では、ソースに手が入れられない、もっと詳しい物を出してほしい」ということらしいのですが、
この場合、量が多ければ良いというものではないと思うのですが・・・

確かに、整理されたドキュメントがあれば、ソースコードの理解を大きく助けるでしょう。
しかし、必要以上に詳細に書かれた物は、それはもはやソースコードと変わらないわけでして、あまり意味がないと考えています。

プログラミングは製造業に例えられることがあります。
製造業では、図面上での設計を経て、実際のモノとなります。
プログラミングでは、ドキュメント上での設計を経て、プログラムとなります。。。？

これには少し疑問で、確かにお客からの要件を確実に満たすために、設計を行って、その結果をドキュメントとして残す作業や、図面上での設計に似ているかもしれませんが、
それは製造業といえでも、別フェーズで行っています。
私の解釈が間違っているかもしれませんが・・・

そもそもプログラムは、モノではなく、
プログラミング言語として記述したものがそのまま（コンパイルやリンクはしますが）動くので、
実際にプログラミングする直前の詳細な設計≒プログラミング なのではないかと思っています。

そんな詳細なドキュメントがあったとして、果たしてソースコードの理解が深まるか疑問に思います。

プログラムの場合、ソースをただ単に読む以外に、
理解できたところに変数の値を出力するコードを埋め込んだり、デバッガで動かしながら様子をみたりすることができます。
明らかな設計ミスでスパゲッティになっているプログラムでは無い場合、
それから、明らかに自分の力量を超えたプログラムではない場合は、なんとかなるものです。
なんとかならない場合は、自身の技術力が足りないだけなのかもしれません。

私も、ネットワーク関連のプログラムはオープンソースのものを読んでいじってみたりできますが、
カーネルの仮想メモリとか難しそうなところは、さっぱりわかりません。
きっとこのあたりのことは、詳細なドキュメントがあっても読んで理解して、改造したりは出来ないと思います・・・

仕事を請けている立場としては、なかなか言いにくいことですが、
ドキュメントの分量を指摘する前に、もう少しソースを読んでほしいなと思ったのでした。

ちなみに、こういう事を言う人の場合、そもそもデバッガの使い方すらわかっていなかったりします・・・