Re: Requirements for Documentation System

Updated list compilation (maintained at <http://wiki.ciaweb.net/yawiki/index.php?wiki=PEAR_Doc> ). Requirements for a PEAR Documentation system, in no particular order: 1. Easy online collaboration between identified participants. ◦ Paul: a web form textarea and a text editor ◦ Arnaud: OpenOffice or similar editor 2. Ability to allow/deny specific users access to specific documents (particularly for editing) ◦ PEAR-DOC and PEAR-QA team members should have full editing access ◦ Package owners should have full editing access to their own packages 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 ;-) 4. Easy to translate the document source to multiple output formats, targets, and languages. 5. Fast turnaround between edits and displayed results ◦ Paul: this means "immedate"; hit "save" and the changes are displayed right then 6. Ability to distinguish between versions of a document 7. Easy to "roll back" or "revert" to a previous version of a document 8. Changes to documentation must send notification to the PEAR-DOC team or mailing list 9. A comment system so that users who are not allowed to edit directly can still be heard within context 10. Ability to preview the edited document (perhaps multiple times) before saving or committing it. 11. Ablility to integrate inline phpDocumentor tags from source code (method and purposes to be determined) ◦ Olivier and Stefan: automatically build API reference from phpDocumentor tags and allow authors to compose additional "handwritten" documentation attached to it 12. Ability to to automate conversion of extant documentation into the system 13. The system itself must be well-documented and open to shared maintenance -- Paul M. Jones Savant: the simple alternative to Smarty. http://phpsavant.com/