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

[Jason T. Greene]

Manik Surtani wrote:
> +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

I think the ideal solution for versioning would be to have a doc for 
every major version (1.x, 2.x, 3.x etc), instead of all versions like we 
have now. For features that are added in minor versions, we can just add 
a little ("new in 2.2" note).

> 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.

Thats a good point.  I think a good compromise on this is allow 
community annotations, similar to the PHP and MySQL documentation. We 
could also grant access to trustworthy contributors that may not commit 
source code.

> 3.  Converting existing collateral from docbook to a wiki.  I for one 
> ain't doing this by hand!  :)
>

Haha there must definitely be a conversion or import process.

> 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.
> 

Yes we should do POC before making any changes(I am willing to invest my 
time on that).

-- 
Jason T. Greene
JBoss, a division of Red Hat