phpDocumentorで素晴らしいドキュメントを書くために

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.pkg.html

何が良いドキュメントにさせるのか？それは一口に言えないが、気に留めておくべきいくつかのことがある。

by Gregory Beaver

読者のことを考えろ

• 誰に対して書けばいいか。多くのソフトウェア（例えばMicrosoft製品）はエンドユーザ向けのドキュメントを書けばいい。しかし、オープンソースソフトウェアは使うことと拡張することがある。この２つの目的を果たそうとしてる人向けに書くべき。

エンドユーザ

• Instruction-style writing, 変数がどのように使われるかよりも、一般的な概念の説明や記述
• Interface information only, no low-level details
• どうやって使うかの例。

プログラマー

• 構成要素の相互作用がどうプログラムされているかの詳細
• Where in the source code an action or series of actions occurs
• どうやって機能拡張するか

これら２つはただのAPIドキュメントやチュートリアルではわからないが、but a subtle blend of the two.

で、phpDocumentorは異なるニーズごとにディレクトリ分けて作成できますよ。
例えば@accessタグを無視したりとか？