次のページ 前のページ 目次へ

1. ドキュメンテーションについての若干の考察

なぜドキュメンテーションを書くのか? 馬鹿げた質問かもしれない。も ちろん、他の人達が、我々が造ったプログラムや、ライブラリ関数、その他のも のを使うことができるようにするためである。しかし、ドキュメンテーション を書くということには、それ以上のものがある。

+ ドキュメンテーションはアクセスできなければならない。

ドキュメ ンテーションに関連するツールが探すことのできない標準的ではない場所に隠 されているなら、目的を達成することができない。

+ ドキュメンテーションは、正確で、信頼のおけるものでなければならない。

プログラムの動作とドキュメンテーションの記述が一致しないことほど、うっ とおしいことはない。ユーザーはあなたを罵り、うらみつらみのメールを送り、 こんな間抜けが書いたものなど、2度とインストールしないと決意をして、あ なたのプログラムを削除してしまうだろう。

UNIX において歴史が有り、良く知られたドキュメンテーションの方法は、 man(1) コマンドを利用するものである。この HOWTO は、ドキュメンテーショ ンに関連するツールによって正しく処理されるために何をすべきかについて説 明する。ドキュメンテーションに関連するツールとして重要なものには、 man(1)、xman(1x)、apropos(1) 、makewhatis(8) 、catman(8) がある。

情報の正確さと信頼性は、もちろん、書き手であるあなた次 第である。しかし、以下の文章は、この観点においても、参考になるだろうし、 よくある過ちを避ける手助けになるだろう。


次のページ 前のページ 目次へ