Re: Lets ditch docbook (long-term)

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
manikjboss.org






_______________________________________________
jbosscache-dev mailing list
jbosscache-devlists.jboss.org
https://lists.jboss.org/mailman/listinfo/jbosscache-dev

+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
> manikjboss.org
>
>
>
>
>
>

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

_______________________________________________
jbosscache-dev mailing list
jbosscache-devlists.jboss.org
https://lists.jboss.org/mailman/listinfo/jbosscache-dev

This week a community contributor sent me some a very tiny
correction to 
the POJO Cache documentation (the word you had an additional
y, "yyou"). 
Updating the docs for such a simple fix is a royal pain in
the ass, and 
required me merging it to 3 different project branches,
regenerating 
documentation using maven (which failed btw, since maven is
a pos, and I 
had to update an already released tag), and finally
committing the new 
docs to the CMS SVN.

This process combined with the unfriendly docbook format
basically 
discourages the docs from being properly maintained.

IMO a good wiki, like mediawiki, is superior to docbook for
community 
documentation, since its easy to update, easy to use, and
allows 
external community members to contribute updates without
getting code 
svn access.

I think we should move our project docs to something like
mediawiki, and 
save docbook for situations when you actually want printed
documentation 
(like EAP).

-- 
Jason T. Greene
JBoss, a division of Red Hat
_______________________________________________
jbosscache-dev mailing list
jbosscache-devlists.jboss.org
https://lists.jboss.org/mailman/listinfo/jbosscache-dev

Jason T. Greene wrote:
> This week a community contributor sent me some a very
tiny correction to 
> the POJO Cache documentation (the word you had an
additional y, "yyou"). 
> Updating the docs for such a simple fix is a royal pain
in the ass, and 
> required me merging it to 3 different project branches,
regenerating 
> documentation using maven (which failed btw, since
maven is a pos, and I 
> had to update an already released tag), and finally
committing the new 
> docs to the CMS SVN.
> 
> This process combined with the unfriendly docbook
format basically 
> discourages the docs from being properly maintained.
> 
> IMO a good wiki, like mediawiki, is superior to docbook
for community 
> documentation, since its easy to update, easy to use,
and allows 
> external community members to contribute updates
without getting code 
> svn access.
> 
> I think we should move our project docs to something
like mediawiki, and 
> save docbook for situations when you actually want
printed documentation 
> (like EAP).
> 

I just heard from Bob that labs is getting ClearSpace, which
not only is 
a modern wiki, but also has docbook integration, so that the
base 
content can be populated from docbook, and edited/added-on
with wiki 
operations.

-- 
Jason T. Greene
JBoss, a division of Red Hat
_______________________________________________
jbosscache-dev mailing list
jbosscache-devlists.jboss.org
https://lists.jboss.org/mailman/listinfo/jbosscache-dev

+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
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.
3.  Converting existing collateral from docbook to a wiki. 
I for one  
ain't doing this by hand!  

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.


On 1 May 2008, at 16:41, Jason T. Greene wrote:

> Jason T. Greene wrote:
>> This week a community contributor sent me some a
very tiny  
>> correction to the POJO Cache documentation (the
word you had an  
>> additional y, "yyou"). Updating the docs
for such a simple fix is a  
>> royal pain in the ass, and required me merging it
to 3 different  
>> project branches, regenerating documentation using
maven (which  
>> failed btw, since maven is a pos, and I had to
update an already  
>> released tag), and finally committing the new docs
to the CMS SVN.
>> This process combined with the unfriendly docbook
format basically  
>> discourages the docs from being properly
maintained.
>> IMO a good wiki, like mediawiki, is superior to
docbook for  
>> community documentation, since its easy to update,
easy to use, and  
>> allows external community members to contribute
updates without  
>> getting code svn access.
>> I think we should move our project docs to
something like  
>> mediawiki, and save docbook for situations when you
actually want  
>> printed documentation (like EAP).
>
> I just heard from Bob that labs is getting ClearSpace,
which not  
> only is a modern wiki, but also has docbook
integration, so that the  
> base content can be populated from docbook, and
edited/added-on with  
> wiki operations.
>
> -- 
> Jason T. Greene
> JBoss, a division of Red Hat
> _______________________________________________
> jbosscache-dev mailing list
> jbosscache-devlists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jbosscache-dev

--
Manik Surtani
Lead, JBoss Cache
manikjboss.org






_______________________________________________
jbosscache-dev mailing list
jbosscache-devlists.jboss.org
https://lists.jboss.org/mailman/listinfo/jbosscache-dev

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).

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

> 3.  Converting existing collateral from docbook to a
wiki.  I for one 
> ain't doing this by hand!  
>

Haha there must definitely be a conversion or import
process.

> 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).

-- 
Jason T. Greene
JBoss, a division of Red Hat
_______________________________________________
jbosscache-dev mailing list
jbosscache-devlists.jboss.org
https://lists.jboss.org/mailman/listinfo/jbosscache-dev

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
manikjboss.org






_______________________________________________
jbosscache-dev mailing list
jbosscache-devlists.jboss.org
https://lists.jboss.org/mailman/listinfo/jbosscache-dev

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

--
Manik Surtani
Lead, JBoss Cache
manikjboss.org






_______________________________________________
jbosscache-dev mailing list
jbosscache-devlists.jboss.org
https://lists.jboss.org/mailman/listinfo/jbosscache-dev

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


The advantages are

    * Potentially more collaboration from the community
    * Quick to change docs
    * *One* source for wiki and docu




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

_______________________________________________
jbosscache-dev mailing list
jbosscache-devlists.jboss.org
https://lists.jboss.org/mailman/listinfo/jbosscache-dev

-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://fedo
raproject.org/wiki/Main_Page
[2] http://moinmoin.wikiw
ikiweb.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
>> manikjboss.org
>>
>>
>>
>>
>>
>>
>
> -- 
> Bela Ban
> Lead JGroups / Clustering Team
> JBoss - a division of Red Hat
>

--
Manik Surtani
Lead, JBoss Cache
manikjboss.org






_______________________________________________
jbosscache-dev mailing list
jbosscache-devlists.jboss.org
https://lists.jboss.org/mailman/listinfo/jbosscache-dev