Mailing-List: contact dev-help@forrest.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@forrest.apache.org
Received-SPF: neutral (asf.osuosl.org: local policy)
Message-ID: <43A56C75.80007@apache.org>
Date: Sun, 18 Dec 2005 14:04:37 +0000
From: Ross Gardler <rgardler@apache.org>
User-Agent: Mozilla Thunderbird 1.0 (Windows/20041206)
MIME-Version: 1.0
To: dev@forrest.apache.org
Subject: Re: Creating documentation (Re: Link to CSS
 howto-structurer-dsl.html)
References: 
 <034043EC81DEDE4CA779BDE7C7E6C7D901F140A4@SDOMSGMB00.corp.fairisaac.com>
 <20051218021940.GB16934@igg.indexgeo.com.au>
In-Reply-To: <20051218021940.GB16934@igg.indexgeo.com.au>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

David Crossley wrote:
> Calmbach, Richard wrote:
> 
>>>-----Original Message-----
>>>From: Ross Gardler:
>>>
>>>(this is a general comment not at all aimed at the authors of 
>>>these mails - since I'm in that group)
>>>
>>>Why is it that people take the time to write clear 
>>>documentation like this but nobody puts it into a document?
>>
>>I noticed that Forrest doesn't have a wiki at http://wiki.apache.org/,
>>unlike many other Apache projects. A wiki may facilitate the creation of
>>documentation for new features that are still under development. There
>>is close to zero overhead in adding and revising content. The additional
>>benefit is that users who want to experiment with the latest code have a
>>central place to go for information. It's sometimes difficult to find
>>specific info in the mailing list archives. Once new features have
>>stabilized, the wiki pages can be converted to xdoc and moved to the
>>official documentation.
>>
>>WDYT?
> 
> 
> As you can imagine, this topic comes up often. We need
> to document our procedure better.
> 
> Here is one such thread. It leads to some others.
> http://marc.theaimsgroup.com/?t=112277292100003
> 
> Instead of putting effort into installing and managing a Wiki,
> we would rather put that effort into using Apache Lenya.
> 
> However, as discussed before, what is wrong with using the
> current procedure like just happened for the forrestbot.html
> and is gradually happening for the Dispatcher documentation?
> 
> You talk about "central place for documentation of latest code".
> That is http://forrest.apache.org/docs/
> and for the bleeding edge, it is at:
> http://forrest.apache.org/docs/dev/
> ... and top-level documents are updated too, e.g.
> http://forrest.apache.org/tools/forrestbot.html

I am a firm believer in a lower barrier to entry for docs. See the links 
above for full discussion, but in sumary learning to use SVN just to 
contribute a 1 para improvement sentence to docs is too much of a 
barrier. The counter argument (again see above links) is that we should 
be encouraging people to learn SVN so they can make contributions to 
other parts of Forrest.

The great thing about the Lenya proposal was that it would support SVN 
as a back end, thus allowing people to work with the tool they prefer. 
Unfortunately, I don't think any progress has been made towards this.

Ross