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

[Bela Ban]

+1 on all points. -1 on using a commercial wiki though... Is mediaWiki 
good enough ?

Manik Surtani wrote:
>
> On 3 Jun 2008, at 14:26, Bela Ban wrote:
>
>> +1 in general, *IF*
>>
>>  1. There is a converter from docbook to the new wiki
>>  2. Ease of use:
>>        1. how easily can I import figures (e.g. PNG), is there some
>>           wysiwyg editor ?
>>        2. Since most wikis have a stupid and very limited markup
>>           language: how powerful is the wiki's markup language
>>           compared to docbook ?
>>
>
> Yes, I forgot to add both of those *very important* points.  
> Especially 1.  No way am I rewriting everything by hand.  :-)
>
> I believe ClearSpace has a wysiwyg editor.  But even then, a lot of 
> the other good wikis now have decent wysiwyg support (MoinMoin and 
> MediaWiki in the OSS camp, and ClearSpace, Confluence in the 
> proprietary camp).
>
> In terms of markup, I think we'd want:
>
> 1.  Basic formatting (headings, bold, italic, links, etc)
> 2.  Embedding images
> 3.  Code snippets with syntax highlighting, support for different code 
> formats, e.g., Java, XML, BASH?
> 4.  Footnotes
> 5.  Being able to easily link to other chapters/sections
> 6.  Tables
>
>> The advantages are
>>
>>   * Potentially more collaboration from the community
>>   * Quick to change docs
>>   * *One* source for wiki and docu
>
> Precisely.  Plus the ability to add comments per chapter or section 
> where the community can attach sample code, etc.
>
>
>> Manik Surtani wrote:
>>> 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?
>>
>> -- 
>> Bela Ban
>> Lead JGroups / Clustering Team
>> JBoss - a division of Red Hat
>>
>
> -- 
> Manik Surtani
> Lead, JBoss Cache
> manik at jboss.org
>
>
>
>
>
>

-- 
Bela Ban
Lead JGroups / Clustering Team
JBoss - a division of Red Hat