このセクションでは、 ドキュメントを論理的に記述する方法ついて述べます。 peardoc の標準に従った ドキュメント構成の仕様を扱うものではありません。
パッケージは、ある問題を解決します。 その問題とは、いったい何でしょうか?。 そして、その問題について、 エンドユーザが想定していないかもしれない前提事項は何かを考えてください （エンドユーザは、その問題が解決すべき事だとすら考えていないかもしれません）。 例えば、テンプレートのパッケージは、コードからのデザインの分離、 ビジネスロジックからのディスプレイロジックの分離という問題を解決するものです。 このとき可能ならば、初心のプログラマが理解できるような用語で説明してください。
パッケージは、どのような方法で問題を解決していますか。 多くのドキュメントが記述していないのが、問題解決の方法についてです。 たとえば、数多くのテンプレートエンジンが存在し、 それぞれが同じ問題を解決しようとしていますが、同じ方法では行っていません。 ブロックベースのテンプレートエンジンはロジックをまったく持っていませんが、 Smarty のようなテンプレートはまったく新しいテンプレート言語を定義しています。 テンプレートをコンパイルするものもありますし、しないものもあります。 パッケージの特徴は何でしょうか? コードを読んでいないユーザも、問題解決の方法について良く理解できるでしょうか?
サンプルをいくつか示してください。 基本的な機能を示すシンプルな例から始めてください。 パッケージをユーザがてっとりばやく使ってみる方法を示します。 さらに、より複雑な例を示すことによって、 より高度な使用方法を理解させるようにします。
もし、（よくあることですが） パッケージのインターフェイスが複雑だったり、 多くの定数があったりして、少数のサンプルでは説明が完全にできない場合、 それらインターフェイスや定数を、ドキュメント中ですべて説明してください。 ユーザが必ず使うことになるインターフェイス、例えば、 データベース DSN やアプリケーションのコマンドライン引数、 設定ファイルの定数、その他すべての非コード的な要素について ドキュメントを作成してください。
最後に、ドキュメントを校正してください。 できるなら、あなたのプロジェクトを良く知らない誰かに ドキュメントを読んでもらってください。 あなたが見落としていた前提事項を捕らえてくれるかもしれません。