Re: RE: [PEAR-DOC] phpDocumentor tutorials/extended documentation implementation

Hi Alex, This is a very clear email, no problems with the time taken to write it! I am happy to see your thoughts because they really do fit with what I think makes useful documentation. Some points that I think we agree on (and would love your input): --private (internal) elements should not be in a public manual --api docs are useless on their own --tutorials are great if up to date, but are more useful when packaged with the manual --redundancies in manuals/tutorials should be eliminated The first point is something that phpDocumentor has always done (only in 0.4.2 was documenting @access private allowed with a command-line switch). In addition, for things that should never be documented, there is always the @ignore tag, new in 1.0 (I think). The second point is what we agree on the most. API docs are useful as a reference once one knows how to use things, but learning how to use something from api docs is extremely frustrating. We do differ on the purpose of comments in a docblock. in phpDocumentor, we place both a summary of how the code works and how to use the code (usually these overlap). Comments that describe the details of working are placed in the source where they are most valuable with //. Since a docblock is by nature designed for public production, it makes absolutely no sense to write it with any other audience in mind. This is what I meant in an earlier comment about bad vs. good documentation. A programmer must write with an enduser who is BOTH a programmer and enduser in mind for something that is open source, this is a basic fact of the code in PEAR. PEAR is also different from the PHP manual in that PHP functions are written in C and not directly modifiable. In other words, many endusers will look at sourcecode if they find that a program doesn't quite solve their problem. API docs should make it easy to figure out where to look in this case, something that good documentation will do. The third point is what I'm hoping to solve with the new idea. Converting a tutorial written in html to docbook is really easy (I'm finding this as we transfer the phpDocumentor manual to docbook). The ability to link to the extended documentation (something the DB docs that you mention do) is a must, and is supported as well. The @tutorial tag works exactly like @see and does *not* include a tutorial in the source code. I don't know if this was clear. In other words, if a DB tutorial named "connect.cls" has a title "Connecting to a database with DB", then @tutorial DB/connect.cls could generate a clickable link in html that would read "See also: Connecting to a database with DB" and allow the user to go to the external tutorial. The docbook converter would use a <link> tag for this same purpose. The fourth point can be easily implemented either by hand (the hard way) or by using the --ignore commandline in phpDocumentor to ignore redundant information in files (like install.pkg, for example). This requires users to separate their tutorials into several files, but this is better for control of output and readability. In addition, for packages that are released both through PEAR and separately, it will allow flexibility in what documentation is created without any extra hassle. I also agree with you that the documentation generated by JavaDoc is not very useful. phpDocumentor itself comes with an extensive manual in the spec/ directory, which is going to be 100% merged into the new docbook format. This new approach will also allow us to create extended documentation for each output converter, for instance, on how to write templates for that particular converter. phpDocumentor is a perfect example of a project that is designed to cater to both users who have no knowledge of the internals and no desire to learn it, and those who need extra functionality and would like to extend it. We will create two sets of external documentation, one for the first user, and the other for the second. This should be possible for PEAR modules as well. The model I'm using for a good manual is the books I used to learn perl, php, html, etc. from O'Reilly/Wrox and other assorted publishers. These manuals consist of a beginning section devoted to a series of extended tutorials, and then a closing reference that describes how each element of the language should be used. This, to me, would be a useful manual, and I believe keeping it up to date is crucial and best accomplished through a tool like phpDocumentor that extracts the most up-to-date possible API reference, and cross-references between the manual section and the API section. I often found myself flipping back and forth when I was learning a new language. The cvs version of phpDocumentor creates tree-like structures of tutorials/extended documentation, allowing grouping of sub-tutorials. An example of this would be the tag specification. There is a basic tutorial that describes what tags are and how to use them, and then a detailed file for each tag. Of course, the docbook-generated html on peardoc doesn't support this hierarchy as far as I can see, but I don't see any reason why an <unorderedlist> couldn't be used to accomplish this with the entities that reference the other tutorials, allowing an even clearer manual. The long, undifferentiated list of things to go to in http://pear.php.net/manual/en/core.db.php gives me a slight headache that would be solved nicely by a table of contents-style listing. In addition, the auto-association of tutorials with packages, classes, or procedural elements means that a programmer who is looking to extend a class can get a headstart by reading the extended documentation for that class. Does this sound more encouraging? I really think we're working to solve the same problem. I would love to make both your job as documentation editor and the programmer's job simpler, and truly believe it can be done. Take care, Greg -- phpDocumentor http://www.phpdoc.org "Alexander Merz" <alexander.merz@t-online.de> wrote in message news:3E005F3C.60309@php.net... > LIMBOURG Arnaud wrote: > > Alex is alive !! > > > > For the moment peardoc is very API oriented as i see it. > No, see ie the PEAR::DB doc. The problem is, only the > maintainer of a package can really write the tutorial, i can only write > the API doc based on the phpdocs. > > To clearify my position as editor: > > Note: > (end-)user = programmer who wants to use a PEAR package > programmer = programmer/maintainer of an PEAR package > > As user, the docs of the JDK or CPAN drives me often crazy. They are > really API docs only. If i want to get a starting point (tutorial), i > have to go Google and starting a query like "CPAN libwww tutorial". > I get a lot of links to docs in txt, html, pdf, ...; some of the links > are dead, some content is just unsatiesfied. > After reading the tutorial and getting the idea of "how it works", i > need an API doc only - but not like the JDK API docs; to much stuff: > private functions etc. The same problem in the code docs of PEAR, a lot > of information refers to internal stuff, nice for a programmer - > senseless and dangerous for a user. > > While thinking about the content of the PEAR manual, i had this in mind. > My idea of the PEAR Manual is: Keep information for beginners and > advanced user in one place = peardoc. > Tutorials are an starting point for a user, they have to be put into > peardoc, because they have to be up to date and bug free as possible - > no maintainer can this guarantee for "his tutorial" on a server > somewhere. Also - i'm sure - the most maintainer/programmer doesn't know > what is in peardoc all together, but i (should) know it as editor. > > I worked on the docs for XML_sql2xml; Christian wrote an really good > tutorial - but it is placed on his server. And it covers information, > which are desrcibed already in the PEAR Manual (installation etc.) - > uninteresting if your are already familar with PEAR. As editor , i can > drop such section and replace them with links to the section covering > this topics in detail; advanced PEAR user can ignore this. They are not > forced to read well knowed stuff. > > And for API doc issue - do not confound PHPDoc API doc with Manual API > Doc. The API doc in the manual should only show the public interface of > an package. It should give a user the information which function he can > use and how to use - not how the package is implemented. Compare the API > entries of the Manual with the API doc entries - they differ in the most > cases. If you are a programmmer, you have to run phpdoc(-umentator) over > the source, the manual will not be a replacement for this. > > Ok, a long mail, written in short time, but hopefully you get i idea of > my thoughts. > > PS: i'm not against the @tutorial tag, but strictly against using it in > PEAR. >