[jbosscache-dev] Lets ditch docbook (long-term)

[Manik Surtani]

+1 on ditching docbook, +1 on Maven being a POS, and +1 on moving to a  
wiki for docs.  :-)

The only issues with wikis as official docs are:

1.  Versioning, since documentation has to go hand in hand with releases
2.  Controlling content - it can't be an open "community" wiki.  We  
already have that, and that is useful, but an official guide should be  
restricted to committers.
3.  Converting existing collateral from docbook to a wiki.  I for one  
ain't doing this by hand!  :)

I think 1 & 2 can be achieved with proper processes, we just need to  
come up with these.  3 should work with ClearSpace, will need to POC  
this though.


On 1 May 2008, at 16:41, Jason T. Greene wrote:

> Jason T. Greene wrote:
>> This week a community contributor sent me some a very tiny  
>> correction to the POJO Cache documentation (the word you had an  
>> additional y, "yyou"). Updating the docs for such a simple fix is a  
>> royal pain in the ass, and required me merging it to 3 different  
>> project branches, regenerating documentation using maven (which  
>> failed btw, since maven is a pos, and I had to update an already  
>> released tag), and finally committing the new docs to the CMS SVN.
>> This process combined with the unfriendly docbook format basically  
>> discourages the docs from being properly maintained.
>> IMO a good wiki, like mediawiki, is superior to docbook for  
>> community documentation, since its easy to update, easy to use, and  
>> allows external community members to contribute updates without  
>> getting code svn access.
>> I think we should move our project docs to something like  
>> mediawiki, and save docbook for situations when you actually want  
>> printed documentation (like EAP).
>
> I just heard from Bob that labs is getting ClearSpace, which not  
> only is a modern wiki, but also has docbook integration, so that the  
> base content can be populated from docbook, and edited/added-on with  
> wiki operations.
>
> -- 
> Jason T. Greene
> JBoss, a division of Red Hat
> _______________________________________________
> jbosscache-dev mailing list
> jbosscache-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jbosscache-dev

--
Manik Surtani
Lead, JBoss Cache
manik at jboss.org