プログラム仕様書は何の為に？ どこまで書けば良い？

「ソースが仕様書です。」と言いたい。その分、ソース内のコメントをしっかりと書く方が良いように感じるってのは言い古されているかな。

そんな事言ったってお上の方には通じないから結局書くんだけれど、誰が何の為にこのドキュメントを読むんだろう、と疑問に思う。目的がお客さんを通じてリーダーさんから伝わってこないため*1、どうすれば良いか非常に迷う。

APIの仕様等、他のプログラマの為？

これであれば、ドキュメント量はそれなりの抑えられそう。

APIのインタフェースと仕様決めちゃえば*1、実装は基本的にプログラマ任せでいいじゃん
(略)
*1：javaでいえばpublicなインタフェースとそのjavadocが書き終わってる状態

これで十分だと思う。「細かいところはソース見てね」が通じそうだ。javadoc等であれば、コード修正毎のついでにコメントも修正で事足りるので整合性も保ちやすい。スパイラルなプロセスの一つとして組み込め、更新の労力が少なく済みそうだ。
SE的な仕事もする事になるだろうオイラとしてはこちらに持って行きたい。

プログラマでないお客さんが内部のロジックを知る為？

これだとかなり厄介。
設計書(日本語) → コーディング(プログラム言語翻訳) → 仕様書(ロジック日本語翻訳)というプロセスを踏むのではないだろうか。実際にコーディングはしていなくても頭の中で思い浮かべているのがプログラマの性というものだろう。どの道ロジックを考えているプログラマにしてみれば、言葉を変えただけで二重のことをしている。その意味でも面倒この上ない。フローチャートなんて書かせられたら気が狂いそうだ。
初期の作成も面倒だが、初期だけで済めばまだ良い方。ロジックの修正が入ったらドキュメントも手直しだ。更新されないドキュメントなど無価値だ。いや、無(0)ならまだ良い、マイナス価値となるだろう。
どうせドキュメントを作っても誰もレビュー時以外は読まないのだ。読むとしたら何か問題が起こった時で、大概ドキュメントは更新されていない。新たに人が入ってきた時も大量のドキュメントに打ちのめされて読みきれないに決まっているのだ。良いことなど一つも無い。
何とかしてお客さんを説得したいところ。できりゃ苦労しなんだろうけど。

*1:リーダーも実は分かってないんじゃないかと思う