Re: Re[2]: [PEAR-QA] Documentation..

On Mon, 6 Dec 2004 22:56:05 +0200, anatoly techtonik <techtonik@php.net> wrote: > Hello Greg, > > >> <opening mouth> > >> I think we mean end-user documentation here, not just API docs, to > >> include short narrative description (3-4 sentences or a couple of > >> paragraphs?) and getting-started examples. > >> <closing it up again> > > GB> no API docs is a bug. No verbose tutorials is a feature request. Would > GB> you say that PEAR_PackageFileManager has no documentation? It is 99% > GB> API docs, but as a part of API documentation, there is a usage example > GB> for important methods. The two kinds of documentation are not mutually > GB> exlusive. > > GB> I like tutorials, but they are not essential to understanding 99% of > GB> packages. What really matters is knowing how to use a method/class and > GB> what the expected usage is. The rest is candy for people who are also > GB> learning how to program at the same time. > > 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. > > I must say, that I'd like to learn to write such cool docs and read some > series of articles called "Writing good documentation", "Introducing > package" or "PEAR designing patterns", but my English is very poor. =( > Every linguistic university has a course how to write an essay, a > bussiness letter, a resume. PEAR has it's CS, packages, but good > documentation is a half of key to success. Take PHP as example. > > As developer in many cases I even can't start writing docs, because I > don't know where to start, what to tell and how to do it. The easy way > to skip the problem is PHPDocumentor. > > As for package manager, I still prefer XML-RPC style. First I'd like > to know what classes exists and what they do (and not to read long > lines like PEAR_PackageFileManager::PEAR_PackageFileManager()). After > that I'm interested in one class only and I want to observe it's > methods. I already know how class is named, so I don't want to search > correct method name among PEAR_PackageFileManager::_______________ > symbols. I need more time to get correct information, because I've got > a lot of superfluous data and that is inconvenient. Like spam. =) > 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. -- Justin Patrin