Personally, I think forest is the right thing to do regarding product documentation (manuals, api docs, user docs). It very version specific and needs to stay with the source code.
That said, project information is NOT product or version specific. The general website could get generated from the WIKI. And I think it's a better medium to use since editing a wiki page is easier to do than updating svn and then generating a site. I too would be willing to help. And I think we can take it in stages. We could easily migrate what you have today in MoinMoin to confluence. Then we could provide the value add of skining those wiki pages so that have the same look and feel that the main site uses that way the main site and wiki look more integrated. Once that is setup, I'm sure you guys will be more comfortable with the process and more information from the main site could get migrated over to the wiki. On Wed, Jul 23, 2008 at 2:15 PM, James Strachan <[EMAIL PROTECTED]> wrote: > 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 > -- Regards, Hiram Blog: http://hiramchirino.com Open Source SOA http://open.iona.com