Hi, Gobas recent mail to this list[1] gave me a good reason to finally post some of the following ideas to the phpdoc mailinglist. These general ideas have been around for some time and I have discussed them with Hartmut, Zak, Goba, Georg, Cornelia at several occasions.
I will propose new/additional approaches to optimise the way the PHP documentation is authored. These are not meant to replace existing workflows, rather to complement them. Here, I will only present the basic ideas for discussion. As I am not a regular reader of this list, I may have missed similar mails, then please be patient with me. 1. Easier Involvement. To open up the documentation team to people who don’t feel comfortable with CVS and plain text XML editing, a solution might be to provide a Browser-based publication tool with WYSIWYG editing for DocBook XML, for example Bitfluxeditor[2]. Such a tool could also provide import/export filters, especially for Open Office XML. 2. Collaboration and workflows. I imagine an online application that allows for virtual teams being responsible for certain parts of the manual. For example, there could be a self-organised team that authors the MySQL functions reference, with specific roles assigned, like “editor”, “author”, “translater”, “proof reader”, etc. 3. Higher transparence of the credit system. Based on the above environment, a more granular credit system could be introduced with information about who authored/reviewed/translated/edited a certain page, chapter, or section. 4. Decentralised Built Process If there were single teams repsponsible for a certain part of the manual, each part could be released/published by the respective team and automatically be built for online display (HTML, PDF, etc. versions), ensuring a faster time-to-publish. 5. Versioning System Just like good Wikis, we could introduce a versioning system to keep track of changes – for “internal” use by the manual teams, as well as for “external” use by the manual readers. I do not talk of the CVS already in use, but of a “markup-aware” diff that presents differences between versions not line-by-line, but e.g. paragraph-by-paragraph or function reference-by-function reference. Maybe we can use existing solutions from Wikis to lower the amount of extra work involved. I head up an Open Source project called “Software 4 Open Communities”[3] that tries to develop such authoring tools. Anything we have done yet, can be considered as a proof-of-concept for some of the above points. The project is currently being re-enginered offline. We do not have the ready-made tools for the proposed collaborative environment, but we have something to start from and are certainly interested to help implementing it. Within the PHP project, other teams might profit, e.g. the PEAR team has already discussed similar aspects to optimise the authoring of the PEAR documentation. Furthermore, I can imagine that an environment for collaborative documentation in online teams is something interesting for other Open Source projects as well, but also for non-programming teams like scientific research teams or departments in companies. Looking forward to read your thoughts on that. Sandro -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
