On Saturday 01 September 2007 09:13, Dossy Shiobara wrote:
> Would there be interest in funding a tech. writer for a short period of
> time?  If we had a fund-raiser, perhaps we could hire one on a contract
> basis for a couple of months?  In that case, what goals would we like to
> set?  Those who would contribute funds: what documentation would you
> like to see authored and/or updated?

Why don't we have an idea-raiser? Maybe it is a common disease among 
programmers: writing code is apparently the only thing which counts. 
Contributions to the community should be for things which are important, 
critical even. Why should we waste time doing unimportant tasks? There really 
are no degrees of importance: either it needs to be done, or it doesn't. Nice 
to have is way down the list. If documentation is so unimportant that it can 
be tasked to a contract tech writer and finished in a few months, why do it 
at all? I can't think of a single use for such a project. Current, very old, 
documentation is okay for beginners. Experienced users are probably not going 
to be helped by documentation written by someone unfamiliar with AOLserver. 

Documentation is more than a formalizm, it needs to have a purpose. Yes, not 
just code needs to be written for a purpose, but the documentation for the 
code needs a purpose.  Nobody knows that purpose of the code, and the type of 
documentation that would best explain it, than those who write and use the 
code. Configuration settings, initialization and runtime information is also 
documentation. Writing code which provides initialization and runtime 
information can't be done by anyone else but the programmer.  

One thing left out so far is example code. Regardless of accepted practice of 
who writes or polishes up documentation in a given project, with no examples 
of use, how did the programmer/engineer test the API? Were there no design 
docs? No goal? If this isn't the exclusive task of a code writer, what in the 
hell is? Of course the programmer/engineer could claim that they just haven't 
written down their thoughts, but it is impossible to maintain that it isn't 
their job. 

My suggestion of revisiting how documentation is done doesn't apply to who 
should be doing it. It needs to be done by those writing, modifying and using 
the code. If someone doesn't think it is important to provide documentation, 
including discussion of goals, motivations, impact, etc. prior to doing 
coding, they don't deserve to be mucking around with the core API; do it in a 
module or in a private copy somewhere. 

We really need to grow up as a community and demand a quality, transparent 
process. The main reason for this is that the current code has not even been 
put into production by AOL. We should assume that this will remain the case. 
In addition, Jim Davidson has moved on, and like it or not, his guidance, 
although not visible, was known, or at least assumed and respected enough to 
accept the process as it was.  Also,  the team which was at least four inside 
AOL has been reduced to almost zero. This proves that we can't even rely on 
AOL to finish what they start. Nor should we, they are a commercial 
enterprise, and should be expected to operate for their own self-interest. In 
fact, we should expect anyone here to do so with respect to their business 
interests. 

BUT this self-interest does not extend into the core API. As community 
members, we need to act in the shared interest of the community.

tom jackson


--
AOLserver - http://www.aolserver.com/

To Remove yourself from this list, simply send an email to <[EMAIL PROTECTED]> 
with the
body of "SIGNOFF AOLSERVER" in the email message. You can leave the Subject: 
field of your email blank.

Reply via email to