geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rodent of Unusual Size <Ken.C...@Golux.Com>
Subject Re: Wiki reorganization proposal
Date Wed, 02 Nov 2005 04:27:20 GMT
Hash: SHA1

John Sisson wrote:
> The suggested layout sounds fine to me.  This is long overdue and is an
> opportunity to remove/move/fix documentation that no longer matches what
> has been implemented.
> My main concern with the use of the Wiki for documentation is that the
> Wiki content isn't versioned to match Geronimo releases.

I think that's pretty significant.  Documentation needs to be
versioned allong with the code.  Just as you can say 'this is
the state of the code as of tag-or-date X' you need to be
able to locate the corresponding documentation (regardless
of how well it has kept up with the code).

Wikis historically have been a collaboration tool, not a
documentation tool.  Working together on docco in a wiki
is great and can speed things up enormously -- but it
needs to get integrated into the SVN repository periodically
for versioning and history retention.

> An alternative is to develop the main documentation under svn control
> (the Derby project does this), but that would mean updates would have to
> be submitted as patches.  Derby's doco can be easily generated as a PDF
> with bookmarks etc, which is great for offline or printing.

The patch model is used a lot, and it has the advantage of
handling the docco the same way the code is.  However, it
doesn't lend itself to quick fixes of typos or contributions
by non-developers.  Wikis are great for that sort of thing,
but have the problems you've already pointed out.

Perhaps some mix would be good, such as a weekly checkin to
svn of any changes to the wiki.  Of course, then there's
the issue of format compatibility.  Do the wikis in use
provide for XML exports?  If so, a little glue should be
able to automatically manage the conversion and checkin.
The major problems I see with that is that the who-changed-what
accountability is lost (unless a change to the wiki can
be included in the export as an XML entity that can be used
to identify the changer in svn), and that changes made
between checkpoints don't get recorded.

There are lots of docco models in use out there.  There's
the patch model which is used by Derby and the httpd
project; there's the user-comments-get-periodically-rolled-in
model that PHP uses; there's the wiki-only method, and probably
lots of others.  I think the documentation should be considered
as much a product of the Geronimo project as the code, and
should be treated with the same care and attention to
versioning, history, and accountability.

My US$0.02.
- --
#ken	P-)}

Ken Coar, Sanagendamgagwedweinini  http://Ken.Coar.Org/
Author, developer, opinionist      http://Apache-Server.Com/

"Millennium hand and shrimp!"
Version: GnuPG v1.2.4 (MingW32)
Comment: Using GnuPG with Thunderbird -


View raw message