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 _______________________________________________ jbosscache-dev mailing list jbosscache-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/jbosscache-dev