Re: Online doc generator

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. 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... 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.