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

Hello Justin, From Monday, December 6, 2004, 11:27:04 PM, you wrote: JP> 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. =) >> JP> If you want quick access to docs, open up the source in your favorite JP> editor and search for the function name. It's the quickest way to get JP> to function docs. Well, where did you read about quick access? I'm speaking about documentation quality. I disagreed with Greg, that documentation should lack tutorials candy. For me it is essential part to get a clear understanding of what package does and how can I use what is does for me. For example it can be clear that types for $me->type can be "string", "integer" and "array", but what this is the type of the whole XML_RPC_Value - this info can be left unnoticed. If you ever tried to implement high level interface with only function docs without understanding that these are must be used in a bunch you will get an understanding of that I mean. As for Greg docs - there's no questions in content quality. I have a deep respect to him seeing all these CVS commits almost every day. It is just about presentation. I don't want to annoy him and if you can spend a little time comparing XML-RPC docs (API chapter) with PEAR_PackageFileManager you will probably note the difference. t --