zookeeper-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "James Strachan" <james.strac...@gmail.com>
Subject Re: Website
Date Wed, 23 Jul 2008 18:15:16 GMT
2008/7/23 Doug Cutting <cutting@apache.org>:
> 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..

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
which include various wiki pages together to form a user manual.

which are then included together in this page

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.


Open Source Integration

View raw message