Re: Online doc generator

On Apr 11, 2004, at 3:07 PM, Alexander Merz wrote:

Paul M Jones wrote:

The real question is: based on what list of requirements did PEAR-DOC (or whoever) decide that DocBook was the best choice? What were the *non-technical* decision points? What were the other alternative technologies discussed?

The history of PEARDoc: I've joined PEAR 2001 or so, i looked for documentation - found nothing (only DB had something on tomas website). Then i wrote a first documentation covering PEAR basics and some packages. This documentation was in german and used docbook. Short time later, we adopted the phpdoc infrastructure because it exists&worked and i started to translate the my docs to peardoc. I followed the discussion about the manual the last months, and decided first not to interact - because the topic "docbook is sh*t" comes up every year. But now i think, i should note some general thinks about writing. First: Programmers want to write code, not documentation. Second: If a programmer want to write documentation, she/he becomes a writer. Third: Writing seems to be hard, because writing is hard and can not by simplified.

I don't totally agree on the Second statement. It takes two to tango. I documented some of the PEAR packages and working on some more. Whilst writing and documenting a package is not a big problem, it becomes a huge problem if you have to spend several hours to figure out what a specific function is doing or what was the desired meaning for the package lead. Some of the PEAR core developers (Jesus, Stig) are respected authors. So saying that a coder can only code and not document is not totally accurate. Among the coding standards we read" Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://www.phpdoc.org/ " so if the code is properly commented, PHPDocumentor can do a great automation job. A professional writer has little interest in writing manual pages (after endless tests) because he might actually have little interest in that package. I documented few PHP functions for the main php.net and well that's a different story. There is no "function lead". Here we have a package lead. He should care about the comments in his source and therefore about documenting his package, providing examples etc. In fact I don't think that we should vouch new proposals with a) insufficient comments as per PEAR coding standards b) no examples

Take care care about the second statement: If you are writer, your first question is not how to write, you first question is how to get readers. A reader does not care about docbook or the collaboration of the authors; a reader want content simple to access and to understand. What means 'to access' - in a format the reader is familar with, but also with a content structure which is easy to memorize. This point means it should not matter which method the reader is looking for, he can expect the parameter names can be found there, a usage example there etc... What means "to understand" - first: the content in general - describing complex things with simple words. Second: that X means X on each page. So why is DocBook good? DocBook was developed by O'Reilly - a publishing company, not a software company. They have to keep up the wishes of authors, lectures and readers in minds. This means: - the format allows to publish online (web) and offline (paper) - forces a high structuriziation of content (see ie. the reference sections in docbook) - allows entities for often used 'words' (URL etc) - brings up a lot of tags to give expression an exact meaning: what a screenshot is, what an example is...

DocBook is fine. What some developers don't like is the learning curve. This is a true story because I found some excellent documentation provided by the package lead (e.g. Template_Xipe) in other formats like PDF, HTML etc.

Your real problem with peardoc is not, that docbook could be the wrong decision, your problem is the missing of *authors*. As author you will love the idea behind docbook, because it helps you the concentrate on the content - and not to think about how to format an 'example' or method name.

I have nothing against docbook. I just think that the current manual situation presents two problems: - Current : many packages are not documented - Future: will new packages fall in the same non documented category ? For the current I plan to link (as suggested by Martin) the existing external documentation to the manual. In this way the user can see the docs, even if hosted by the package lead. Is not a final solution but can help. For the future we do need to ask some documentation to be available in the external site, pear manual or just somewhere. I second your view on "the real problem are missing author" but comments to generate some documentation are required by the coding standards. Furthermore my distinction on the writer/non writer is different. You don't need to be a writer to document your own package. If the package lead can't explain what your package does to someone else, then this is a problem.

Regards,

David Costa, Dotgeek.org

PHP-PostgreSQL Advocacy team     http://dotgeek.org

gurugeek att php dot net david at postgresql ddoot org