Re: Online doc generator

Just a quick 2 cents --- Paul M Jones <pmjones@ciaweb.net> wrote: > On Apr 10, 2004, at 8:11 AM, Lukas Smith wrote: > > > Arnaud Limbourg wrote: > > > >>>> Please tell me why we shouldn't drop docbook. > >>> > >>> Livedocs. Actually people on pear-doc are working to make the > >>> peardoc module work with livedocs. This will hopefully sooner than > >>> later allow us to have HTML output of our docs in real time from > >>> docbook. > > 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? > > We seem to be going at it backwards: requirements *first*, technology > and implementation *later*. We make our clients do it, we should do it > ourselves. > > I would argue we have these minimum requirements: > > 1. Easy online collaboration between identified participants. That is more an organizational and support apps issue. The PHP Documentation teams have created already the support tools, and an example on how to organize the teams. Remember that there we not only have the main english manual, but also about 31 translations, so the solution seems scalable in that sense. BTW, as pointed out, a good part of the PHP manual has been written by people doing only documentation, not the ones writing the code. Oftentimes I remember bothering the person who wrote a particular PHP extension, if I did not understand the code, in order to write documentation for it. We sorely need people in the extended PEAR community that are willing to ddo just that. > 2. Ability to allow/deny specific users access to specific documents > (particularly for editing). Why? CVS works well for collaborative systems. Rarely I've seen problems in the PHP Doc list where people are trampling on each other toes, and those have usually been solve by the people in question talking. I don't think this point has any usefulness for a manual writing effort like PEARDOC. > 3. Easy to learn the markup to lower barriers to entry (docs are less > sexy than code, let's make it easy to get into them ;-) Huh? What is so difficult about XML? I still do not fully understand what is the problem. Agree that I've been using DocBook for quite some time (when I used to be more active on the PHP Doc team), but if a crazy scientist like me can use it ... :-) If you need documentation, there is plenty of docs on how to write manual entries in the PEAR manual and in the PHP manual too (http://php.net/dochowto). The differences between PEAR DOC and PHP DOC are small, so I doubt that the a prospective author will have problems if she uses the PHP or PEAR Manual docs as a templates to start documenting. The crux of the matter is to get people involved doing documentation. I know I am guilty of not documenting my own packages and only offering their full API (using PHPDocumentor). But I not always have the free time I'd like (in particular with my new job). > 4. Easy to translate the document source to multiple output formats, > targets, and languages. See cvs.php.net, count how many translations are there for the PHP manual (phpdoc* dirs). There is already a set of supporting tools to help with all the things you mention above. All translations use DocBook w/o a problem AFAICT. > 5. Fast turnaround between edits and displayed results. How *fast*. If you have a machine to build the PEAR manual running daily, yesterday's edits will be there tomorrow. We are not yet at the size of the PHP Documentation (1500+ pages IIRC) > 6. A comment system so that users who are not allowed to edit directly > can still be heard within context. We have in the PHP Manual, the PHP-GTK Manual has it too, we just need to re-use that code (available on cvs.php.net also) and modify it to the structure of PEAR's Web site. No problem there. > What are the other requirements for the PEAR document > creation/editing/delivery system? > > >> To add to the topic. Bertrand suggested a CMS, I also think it would > >> be good idea to have that or a wiki, so people can easily add > >> documentation. > > > > I agree that a wiki would be good to have. > > > > Actually with Paul's efforts we more or less have a wiki. If he > > wouldnt constantly break the test wiki I could even show it off to you > > all ;-) > > > > *nudge* *nudge* > > Yeah, yeah, once I can leave DB_Table alone I can leave the wiki alone. > :-) Agree with that. In my experience, mailing lists/irc/IM are good places to discuss out things, wiki/web sites good places to document the decisions taken in the discussions. [...snip...] ===== -- Jesus M. Castagnetto (jcastagnetto@yahoo.com) Research: http://metallo.scripps.edu/ Personal: http://www.castagnetto.org/ PEAR stuff: http://pear.php.net/user/jmcastagnetto __________________________________ Do you Yahoo!? Yahoo! Tax Center - File online by April 15th http://taxes.yahoo.com/filing.html