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

[Manik Surtani]

-1 on using a commercial wiki, *unless* that is where JBoss.org is  
headed.  And I believe the answer there is ClearSpace.

Wikipedia.org runs on MediaWiki.  So does fedoraproject.org [1].   
Plenty good.  MoinMoin [2] is pretty nice as well.

[1] https://fedoraproject.org/wiki/Main_Page
[2] http://moinmoin.wikiwikiweb.de/


On 3 Jun 2008, at 15:39, Bela Ban wrote:

> +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
>

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