Re: [jbosscache-dev] Lets ditch docbook (long-term)
On 1 May 2008, at 18:13, Jason T. Greene wrote:
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).
Yeah, works... except that you could end up "losing" user comments as
mentioned in your next section. Unless these are added to the
official docs in subsequent 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.
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.
That's actually a really good idea. I really like the way the PHP and
MySQL docs evolve with proper user comments. I'm guessing these are
moderated/cleaned up though.
> 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).
Cool, let's see what ClearSpace looks like when it is available on
JBoss.org.
Cheers
--
Manik Surtani
Lead, JBoss Cache
manik(a)jboss.org