geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Geir Magnusson Jr." <ge...@apache.org>
Subject Re: Wiki reorganization proposal
Date Fri, 04 Nov 2005 02:02:41 GMT

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
geirm@apache.org



Mime
View raw message