James Cox wrote: > not meaning to be devil's advocate here, but has anyone taken a look > recently as to how we do documentation at php.net ? we use the sgml docbook > format, and generate pages accordingly. We have a notes system, so people > can annotate / comment on, which get reviewed by the documentators (with > edit/delete/reject tools) ? > > This could be made accessible if it's usefull...
Neat! As a user of the PHP docs, I love 'em, and I'd hope that system at least serves as the interface target as far as an annotation and browsing system goes for the revamped moz doc system. What is the interface for the doc authors? Do they have to work through a traditional CVS interface? What if a new contributor wants to submit a changed draft of the doc itself? Would they email diffs to the owner? I think part of the rationale behind using the Zope CMF (which isn't as well-developed a documentation viewer as PHP's docs) is that it offers fully web-based workflow and makes it unnecessary out of the box for contributors to use CVS, whil still letting hardcore techies use FTP or WebDAV to work on documents in a more traditional way. One of the goals seems to be to lower the barrier for contributors. Basically, if it came down to the two it's a choice between a fully developed CMS and workflow system that needs customization to make it an ideal annotated documentation viewer (Zope CMF) and a fully developed annotated doc viewer that needs customization to address the workflow goals (PHP.net's doc system). -- -sk
