apr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tom Bradford <bradford...@gmail.com>
Subject Re: Documentation Project
Date Mon, 24 Apr 2006 21:06:20 GMT
On Apr 24, 2006, at 4:54 PM, Davi Arnaut wrote:
> IMHO, Inoue Seiichiro's tutorial goes out of scope (eg, describing  
> what
> a thread is, et cetera). What kind of documentation you're most  
> interested
> in ? Guides, how-to, tutorial..

Describing what a thread is, how a socket works, etc, are all part of  
a greater whole wherein you give a reader a proper context in which  
to work and learn.  Presenting a threading API to someone who doesn't  
know the fundamentals of threads provides absolutely no value.  On  
the other hand, providing a few extra paragraphs to serve as a  
foundation for the simplified threading APIs that one is about to  
learn goes a long way toward 'selling' your project to a much broader  

For example... reading the doxygen docs, I saw the words 'bucket  
brigade', and my first inclination is to ask 'what the hell is a  
bucket brigade?'.  I knew what a bucket it is, but my understanding  
of a bucket was from a very broad perspective, so giving a foundation  
for these things rather than the pure technical mumbo-jumbo will  
afford you a much larger audience by reducing the learning curve,  
which in my experience (partly with Apache Xindice, but also with  
other projects) is a major stopping point for projects such as these.

Maximum return for minimal investment.

Tom Bradford - http://www.tbradford.org/

View raw message