良いドキュメントを書くコツ

このセクションでは、 ドキュメントを論理的に記述する方法ついて述べます。 peardoc の標準に従った ドキュメント構成の仕様を扱うものではありません。

1. パッケージは、ある問題を解決します。 その問題とは、いったい何でしょうか?。 そして、その問題について、エンドユーザが理解していないかもしれない 前提事項は何かを考えてください （エンドユーザは、その問題が解決すべき事だとすら考えていないかもしれません）。 例えば、テンプレートのパッケージは、コードからのデザインの分離、 ビジネスロジックからのディスプレイロジックの分離という問題を解決するものです。 このとき可能ならば、初心のプログラマが理解できるような用語で説明してください。

2. パッケージは、 どのような独自の方法で問題を解決していますか。 多くのドキュメントが記述していないのが、問題解決の方法についてです。 たとえば、数多くのテンプレートエンジンが存在し、 それぞれが同じ問題を解決しようとしていますが、同じ方法では行っていません。 ブロックベースのテンプレートエンジンはロジックをまったく持っていませんが、 Smarty のようなテンプレートはまったく新しいテンプレート言語を定義しています。 テンプレートをコンパイルするものもありますし、しないものもあります。 何が、パッケージの特徴でしょうか? コードを読んでいないユーザも、問題解決の方法について良く理解できるでしょうか?

3. サンプルをいくつか示してください。 基本的な機能を示すシンプルな例から始めてください。 ユーザに対して、パッケージをすばやく使い始める方法を示すことができます。 さらに、より複雑な例を示すことによって、 ユーザはより高度な使用方法を理解できるようになります。

4. もし、（よくあることですが） パッケージのインターフェイスが複雑だったり、 多くの定数があったりして、1、2のサンプルでは完全に説明ができない場合、 それらインターフェイスや定数を、ドキュメント中ですべて説明してください。 ユーザが必ず使うことになるインターフェイス、例えば、 データベースDSNやアプリケーションのコマンドライン引数、 設定ファイルの定数、その他すべての非コード的な要素について ドキュメントを作成してください。

5. 最後に、ドキュメントを校正してください。 できるなら、あなたのプロジェクトを良く知らない誰かに ドキュメントを読んでもらってください。 あなたが見落としていた前提事項を捕らえてくれるかもしれません。