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

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. =) t --