documentation or lack thereof

["John S. Denker" <jsd@monmouth.com>]

I wrote:
 >>From the keen-grasp-of-the-obvious department:
 >>This project would be a lot better off if there were
 >>better documentation, and (some) comments in the code.


Then on Thu, 05 Dec 2002 10:23:08 -0500, Paul Davis wrote:
 >
 >actually, i have to note that this is not so obvious. there are *many*
 >people using ALSA. we've all sworn our way through the process.
 >there is *no* point in reminding this list about the need for
 >documentation. the current state is pitiful, ...
 >  many folks seem to think there is a
 >large group of people working on ALSA: there is not.

I have tried and failed to understand that remark.  I
stumble over the following apparent inconsistencies:
  ++ On one hand we agree that the current state is pitiful.
  ++ I would think and hope that reminders are almost
     unnecessary because the pitifulness is so obvious.
  -- But why start out by saying it is not obvious?
  -- Usually swearing is not considered a good thing.
  -- And note that if the documentation were better,
     more people would be willing and able to help
     work on the project!  In a collaborative project,
     lack of documentation and short-handedness create
     a vicious circle!

To look at the same glass from the half-full perspective,
Takashi wrote:

> recently i wrote a small howto for writing an alsa-driver.  

That's good!

> please check the archive of alsa-devel ml.

It would be even better if the howto were integrated into
the project package, not hiding in a list archive somewhere.
Maybe even comments in the code linking to the howto, so
people can find it when they need it.



-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf