濱井です。
2001/10/10 23:28:52 +0900にando@....jpさんが送られた
メールに関する返信です。
> 確かに、ドキュメント書くのはめんどうな仕事ですし、そし
>てそのプロジェクトに初めて投入された場合でもないかぎり、
>無味乾燥な文章なんて普通はあまり読みたがらないもです。
>
> ようは、いかにして書かせる。または読ませる気にさせるか。
>という技巧が必要なのだと思います。
>
>＃ それがむりやりなのか、楽しくなのかは置いておいて。
ユーザ向けのマニュアルとか以外のそういう風に労力を要する
ようなドキュメントは作らない方がいいのでは？それが、
「ドキュメントを書くな」ということなのだと思います。
正確なドキュメントを書こうとすると、往々にして煩雑で
わかりにくいドキュメントになりがちです。正確だがわかりにくい
ドキュメントは、読む人に誤解されやすいです。正確さに乏しい
ドキュメントと実質的に大差ないことになります。正確な
ドキュメントを書くのは、手間がかかる割に効果がうすいことに
なります。
それならば、その労力を別の面に向けた方がいいでしょう。それが、
「ドキュメントを書くな」ということになるのだと思います。
> それに対抗するにはやはり javadoc のように、説明をソース
>コードに直接書き込んで、リバースエンジニアリングで仕様書作
>成したりするようなツール作ってみる、などというのはどうでしょ
>う？ (別に javadoc そのものでも良いですけど)
>
> なにしろコード上ですから、当事者のプログラマの目にも付き
>やすいですし、仕様書の差分も軽減しますから、多少は読んでも
>らえるかなと、思うのです。
> まぁそれでも、他の人が見てコード読むより楽だ。と思わせる
>ことができないとやっぱりなかなか読んでもらえないのですが。
ソースとドキュメントの一体化という考えは、KnuthのLiterate
Programmingなど、以前からありますが、あまり普及していません。
本格的にやろうとすると、負荷が高すぎるのかもしれません。
# TeXもWEB(!=WWW)を使っていたんだけど……。