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

[Manik Surtani]

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