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

On Tue, 7 Dec 2004 02:20:34 +0200, anatoly techtonik <techtonik@php.net> wrote: > 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? What I read in that last paragraph in yoru e-mail was that you knew what class you were looking at and what function you wanted docs for. In this case, looking at the API docs is the easiest and quickest was to get the docs. > 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. > We know that the user docs are not very well filled out. This is open source and it's unfortunately that way much of the time. People don't have the time or will to write great code and great docs. You pretty much have to just deal with it. > 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. > -- Justin Patrin