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
4. Markup format should support all semantics necessary for useful display of...
   • prose narrative
   • example code blocks
   • code snippets in narrative
   • some form of tables
   • linking between sections either directly or indirectly related to the current document
   • inline display of images (JPEG, GIF, PNG)
   • example output blocks (e.g., rendered HTML)
5. Easy to translate the document source to multiple output formats, targets, and languages.
   • Haruki: Make the translator's job as easy as possible
6. Ability to mark a document as "ready for translation"
   • Haruki, et. al.: Documentation primary-source language should be English
7. Fast turnaround between edits and displayed results
   • Paul: this means "immedate"; hit "save" and the changes are displayed right then
8. Ability to distinguish between versions of a document
9. Easy to "roll back" or "revert" to a previous version of a document
10. Changes to documentation must send notification to the PEAR-DOC team or mailing list
11. A comment system so that users who are not allowed to edit directly can still be heard within context
12. Ability to preview the edited document (perhaps multiple times) before saving or committing it.
13. 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
14. Ability to to automate conversion of extant documentation into the system
15. The system itself must be well-documented and open to shared maintenance

Wed, 14 Apr 2004, 15:08