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

[Manik Surtani]

I'm cc'ing Mark Newton on this thread.

I'm about to start work on 3.0.0, and 3.0.0 would be a nice "boundary"  
around which we can switch documentation systems as well.

So in summary:

* Maven is a Piece Of Sh*t.
* Docbook isn't much better.
* UserGuide, FAQ and Tutorials are better maintained on a wiki.
* One for each *minor* version.  E.g., http://docs.jbosscache.org/wiki/3.0/UserGuide 
  and http://docs.jbosscache.org/wiki/3.2/UserGuide, etc.
* Wikis should be read-only to the public.
* Logged in members on jboss.org should be able to add comments on any  
page, like MySQL and PHP docs.
* Admins (committers) should be able to edit the docs themselves.
* A "generate PDF" feature should be available, so people can get a  
hold of printable copies of the user guide, tutorial, etc.
* Stop shipping docs with JBC distros and point people to the online  
resource.

What do people think?

Mark, does ClearSpace offer what we want from such a "documentation"  
wiki?

Cheers
Manik



On 2 May 2008, at 09:43, Manik Surtani wrote:

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

--
Manik Surtani
Lead, JBoss Cache
manik at jboss.org