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

Hello Justin, >> >> 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? JP> What I read in that last paragraph in yoru e-mail was that you knew JP> what class you were looking at and what function you wanted docs for. JP> In this case, looking at the API docs is the easiest and quickest was JP> to get the docs. Sorry, you absolutely right. I prefer two kind of docs - one is end-user tutorial to get package picture (to know what class do I need) and second is html-style crossreferenced PHP sources without PHPDoc headers if possible, because I prefer to read and navigate the code and sometimes I found myself completely lost scrolling among 20 variables definitions with 4 lines each in 4 or 5 methods. Among these variables 90% of them is important only to a developer of this package and I can figure their function much quickier without these comments. I like PHPDoc blocks, but I about reasonable use without strict CS rules, which drive devs to put them here and there in a very evil style for reading like: /** * @var array temporary array */ $temp_arr = array(); or even worse /** * @var array */ $zzz = array(); One line comment is enough. That will ease the task of scrolling the sources. Like it is implemented in DoxyGen. $zzz = array(); /*!@var array or something like that Also class blocks could be put in end-user documentation rather than in sources, because without real examples they do not introduce class fully and with these examples PHPDoc blocks can turn into really bloated comments and navigating through source and bugtracking can become a real problem without special editor. Yes, I'm devotee of separating code from end-user documentation. Developers comments should be present only in places others can find troubles. So if smb. will meet difficulties with comprehension - he can add some short (and only really necessary) comments in sources or propose an additional chapter for tutorial if it is a lot of text and concerns package use. Otherwise he can place that comment on a package wiki on special "package innards" page. >> 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. >> JP> We know that the user docs are not very well filled out. This is open JP> source and it's unfortunately that way much of the time. People don't JP> have the time or will to write great code and great docs. You pretty JP> much have to just deal with it. Maybe they have will to write (I believe everybody wants his package to be the best), but they don't have time or don't have necessary skills. But even when they will have some time they can require some help to be able start with the right position about package, to know common questions to answer. Writing good documentation is vital for package and everybody agrees. What if smb. who has an experience can outline general flaws in current Docs and do a short essay about "Writing good documentation?" I believe, that during software lifespan there are quite common techniques and well defined rules drawn how to make documentation readable, what to start documentation with, how to uncover product potential, how to provide an examples and so on. This will be useful for everybody - not only for PEAR developers. t --