Re: Documentation..
| From: | Justin Patrin | Date: | Mon, 06 Dec 2004 22:02:02 +0000 |
| Subject: | Re: Documentation.. | ||
| References: | 1 2 3 4 5 6 7 8 9 10 | Groups: | php.pear.qa |
| Request: | Send a blank email to pear-qa+get-2090@lists.php.net to get a copy of this message | ||
On Mon, 06 Dec 2004 15:45:58 -0600, Paul M. Jones <pmjones@ciaweb.net> wrote:
> 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).
I do realize all of this and I agree. Good "tutorial-style" docs are
great. I was responding to his last statement that he knows what
function he wants and wants the docs for it. The API docs/source are a
great place to look for that.
>
> [*] Who here still has a VCR? ;-)
>
--
Justin Patrin