Re: [jbosscache-dev] Lets ditch docbook (long-term)
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