>> >> The Solution << >> I propose we create a free, high-quality electronic book (entitled >> _The_Cocoon_Handbook_), which will eventually replace the mess of docs >> we currently have. It will be in DocBook (possibly simplified) format. >> >> We can integrate the eventual book with user-added notations, similar >> to how PHP lets people log in and annotate the existing docs. >> >> - The Wiki. >> We need to be able to allow people to annotate or refine the docs >> with ease. How can this be done?
I too wish to see docbook as a documentation format for cocoon and a whole host of other projects. PHPs model of how to get user input into documents is the best I have seen. The comments section is inspired. I've recently been trying to find tools for team based docbook editing. I have experimented with the php doc book wiki (see http://doc-book.sourceforge.net/homepage/ for the project home page) Unfortunately it is not very highly functional (though much better that nothing) and the installation is a PITA and involves measures that leave me not happy with the security aspect (wrapper runs web invoked processes as root). I haven't seen anything for collaborative editing of docbook that I thought would be useable by anyone without a decent understanding of docbook itself. Even for a single user desktop type experience the main barrier to docbook is the editing tools. Most of them are super power user stuff (emacs, command line etc). There are some nice xml editors like xmlmind that can give a wysiwig-ish type experience (there is also http://www.syntext.com/products/serna/index.htm which has out of the box support for docbook and has a free trial). However even these are ugly when you want to do complex stuff. e.g. try putting a helpful screenshot image in your document, I spent half an hour and failed completely even when resorting to hand editing xml. I dream of a cocoon/forrest or lenya based docbook wiki. I think all the constituent parts required are there they just need tied together into an app. However I don't have the time at the moment to do anything about this dream. I suppose what I'm driving at is that an ideal communal editing app would support wiki style editing of simple content (for an average user adding simple paragraphs of content). It would also have to support users of desktop powertools because I can't see anyone achieving more complex editing feats (images etc) via a wiki. >> That's about all that my brain can spew out for now. I really think >> this is a good idea, and I've been throwing the idea around in my head >> for a while now. Undoubtedly and if you can get it right I can see many projects using it. The ability for an editor to post a bare bones structured docbook and then have wiki style community flesh it out would be awesome. Unfortunately I can't offer any real practical help as my cocoon knowledge it too shallow and I'm too busy at the moment.
