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

[Manik Surtani]

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 at jboss.org