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

+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