Re: Interesting Anti Pattern...

[J Aaron Farr <fa...@apache.org>]

On Mon, 2003-12-15 at 02:27, Niclas Hedhman wrote:
> <quote src="http://www.keelframework.org/mission.shtml" >
> Anti-Pattern: Documentation Problems
>
> The best feature of open source is also its downfall - wildly varied forms of 
> documentation, with its most important form also being its most problematical 
> - mail lists. Funny thing is, most of the time it isn't just a lack of 
> documentation, there is usually too much, and you can't find what you need 
> without going through email archives for hours at a time. 
>  
>  Solution:
>  Keel attempts to reduce documentation to javadocs, and online FAQ's editable 
> by users, such as with Wiki. Email is the big problem, and we request users 
> to not use it for documentation - if you answer a question, answer it in the 
> Wiki FAQ, and use email only to furnish a link to right place in the Wiki 
> FAQ. 
> </quote>
> 
> Do we have this problem?

Yep.

We have a HUGE wealth of information in our mailing list archives and
only a small fraction of it is captured in our wiki or site.

Our documentation has a ways to go.  We've made improvements (the new
site is much better than the last iteration IMHO), but it's still not
user friendly enough.  For example, we don't have a good "Getting
Started With Avalon" section or tutorial -- and I'll take the blame for
that one.  I've started on such a tutorial a number of times, but never
finished it.  Now that I've finished my last semester of school I hope
to finally deliver the goods.

We're getting better but there is a LONG way to go.

-- 
 jaaron  <http://jadetower.org>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@avalon.apache.org
For additional commands, e-mail: dev-help@avalon.apache.org