-----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-----
