From mboxrd@z Thu Jan 1 00:00:00 1970 From: "John S. Denker" Subject: documentation or lack thereof Date: Mon, 09 Dec 2002 09:54:10 -0500 Sender: alsa-devel-admin@lists.sourceforge.net Message-ID: <3DF4AE92.3010206@monmouth.com> References: <3DEF5865.7060109@monmouth.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <3DEF5865.7060109@monmouth.com> Errors-To: alsa-devel-admin@lists.sourceforge.net List-Help: List-Post: List-Subscribe: , List-Unsubscribe: , List-Archive: To: Takashi Iwai Cc: Paul Davis , Uros Bizjak , alsa-devel@lists.sourceforge.net List-Id: alsa-devel@alsa-project.org 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