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

+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 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(a)jboss.org _______________________________________________ jbosscache-dev mailing list jbosscache-dev(a)lists.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

+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(a)jboss.org > > > > > > -- Bela Ban Lead JGroups / Clustering Team JBoss - a division of Red Hat