geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hernan Cunico <hcun...@gmail.com>
Subject Re: Wiki reorganization proposal
Date Thu, 03 Nov 2005 14:28:54 GMT
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.

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?

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.

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

Mime
View raw message