On Nov 3, 2005, at 9:28 AM, Hernan Cunico wrote:
Hi All,
It seems like we all agree that versioning is extremely important
although still not too clear to me what would be the versioning
strategy.
with conventional documentation, where it's part of the project SVN
or CVS tree, it's really easy - when you cut a branch for a release,
you are also including the documentation.
Still regarding to documentation and equally important is where to
place the documentation. Apache wiki and Confluence are 50/50. I
believe having the documentation all spread out across several
places and formats is as bad as not having documentation. I
personally think Confluence is more flexible (export to other
formats), has better formating and more user friendly. Should we
propose voting to have this issue addressed?
Voting won't change the fact that a wiki (MoinMoin|Confluence) is a
collaboration tool :)
My preference would be to *not* use a wiki, be it MoinMoin or
Confluence, for project documentation (maybe use Confluence as an
editing tool if it could export a useful format that could be
consumed by other renderers?).
I have not seen many comments back on the reorganized structure
itself. I would really like to see some more interaction there.
Last but not least, should we start creating one major section for
each major release (M4, M5, ...) on the wiki (or confluence)? This
would be the first step forward in the reorganization.
Well, that's what doing docs in the project get you - there is a
natural progression of versions, as they get "carried along" with the
code version.
geir
Cheers!
Hernan
Rodent of Unusual Size wrote:
-----BEGIN PGP SIGNED MESSAGE-----
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!"
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (MingW32)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org
iQCVAwUBQ2hAKJrNPMCpn3XdAQJTkgQAzqd9n9viIJKEmIR31rsbkv5+6YyN+9Nd
4cxDpJDoz037ZIZ/wo8XrKughZlltgcedECEDvOd/XQ4jTdSFS0OhVK2FRwpTIsH
Novl7V1Z/3p7Gb9MT6NlEhbKSn/RrCw0296fKNbLo1kz/+Db2r6B3WYJ8TpoeJri
BXv+kYkfJT4=
=VPrR
-----END PGP SIGNATURE-----
--
Geir Magnusson Jr +1-203-665-6437
[EMAIL PROTECTED]
