Re: Documentation..

Hi, Justin,

On Mon, 6 Dec 2004 22:56:05 +0200, anatoly techtonik <techtonik@php.net> wrote:

The best user docs I ever used on PEAR is XML-RPC. No class::method gibberish in TOC. All on one page in right order of introduction for inexperienced user and also a good logical reference, structurized by logic and not by alphabet. Since every package need special approach, tutorial is the best way to introduce package logic. ...

If you want quick access to docs, open up the source in your favorite editor and search for the function name. It's the quickest way to get to function docs.

Anatoly is distinctly *not* talking about automated API docs, which may or may not be available from the inline comments. He is instead pointing out that hand-written API documentation is valuable specifically because it is *not* automated -- the doc author gets to address the methods in a progression that makes sense to the new user. Automated docs, while useful for reference, are not suited to learning how to use a class; an alphabetical list of functions does make clear the relationships and methodology anywhere as well as a handwritten overview and explanation. To advise a new user to "read the source code" is not a viable alternative to having real handwritten end-user documentation. It's like saying "if you want to learn how to program your VCR [*], you have the tools to examine it: open it up and trace the circuits, it's all there if you look." While technically true, it is no replacement for a manual. I'll buy a VCR that has a manual instead (or curse the VCR company and resent them for being so unfriendly -- or build my own). [*] Who here still has a VCR? ;-) -- pmj