2008/7/23 Doug Cutting <[EMAIL PROTECTED]>: > James Strachan wrote: >> >> Tools like wikis are personal things; and folks tend to prefer to use >> the tool they know. > > That's a key point. > > To make a switch you'd need: > 1. Someone familiar with Confluence to lead the transition, convert the > existing website and wiki content, set up static export etc. Are you > volunteering?
I would yes, but only if 2) gets approval. > 2. Buy in from Zookeeper's primary contributors, who will end up writing > and maintaining the documentation (Pat, Ben, etc.). I don't really count, > since I'm mostly a kibitzer here. > > Also, with Confluence export, how does one deal with versioning? A > convenience of keeping documentation in subversion is that it gets versioned > with releases. By maintaining the trunk documentation to match the trunk > implementation, we automatically get documentation that matches each > version, but we can still maintain the documentation in release branches. I > don't see how this would not add overhead with Confluence exports. If > Confluence always represented trunk, and we exported at release branch > points, then it would be hard to patch branched documentation. Maintaining > multiple branches in Confluence would add management overhead, since these > would need to be synchronized with subversion branching, tagging, etc. How > have other projects dealt with this issue? BTW MoinMoin has the same issue; when documentation is in the wiki you need to grab a snapshot of it to include in releases (or add it to svn) to support versioned documentation. What we've done in the past is copy the static HTML from the wiki with releases; or in some projects we turn the HTML from Confluence into a proper manual in PDF or HTML format. e.g. if you download 1.4.0 of Camel.. http://activemq.apache.org/camel/camel-140-release.html and look in the docs directory; you'll see a manual in PDF and HTML format. Thats generated from the wiki whenever there is a release from these pages http://activemq.apache.org/camel/book.html which include various wiki pages together to form a user manual. which are then included together in this page http://activemq.apache.org/camel/book-in-one-page.html Maybe moving away from Forrest is a step too far right now; but its certainly worth thinking whether for the wiki content its gonna be MoinMoin or Confluence. Only if you choose Confluence then you can consider generating a user manual or the static website from it (neither AFAIK are possible with MoinMoin). Incidentally a totally different thought; whats gonna be the split between whats the static website (e.g. Forrest) versus stuff thats in the wiki versus documentation that goes inside each release? Its often a kinda slippery slope figuring out which bit does what and its a PITA moving content into different formats to move between them; so while no tool is perfect, I kinda like that with confluence there's just one place to put docs and you can then slice and dice as you see fit (and make multiple spaces if you want & share content across spaces) to deal with different version issues etc. -- James ------- http://macstrac.blogspot.com/ Open Source Integration http://open.iona.com