ALSA documentation project?

[Kevin Conder <kwconder@yahoo.com>]

Abramo Bagnara <abramo.bagnara@libero.it> wrote:
>Documentation has not been written for lack of funding and lack of
>volunteers.

Well, I've come foward a few times as a documentation volunteer and
have been frustrated at every turn. The first time I volunteered, the
ALSA team suddenly switched from the DocBook standard (which I am
familiar with) to doxygen. Also, the alsa-doc mailing list was taken
off-line.

The next time I volunteered, a member of the ALSA team blew me off. He
refused to answer my questions directly and told me to ask them on the
*alsa-users* mailing list instead! I felt disrespected and definitely
not a member of the ALSA team.

The last time I volunteered, my hard work was attacked on this list as
being "mechanical". Then a Wiki was implemented and my work was thrown
out. That was the last straw!

So I'm working on the Alternative Csound Reference Manual
(http://www.kevindumpscore.com/docs/csound-manual/) these days. 

As a frustrated former documentation volunteer, here is my advice:

1. Identify the documentation tasks that need to be done and
maintained.
2. Start an ALSA documentation project.
3. Restart the alsa-docs mailing list.
4. Never switch documentation standards without discussing it first.
5. Put a responsible person in charge of coordinating the submissions,
tasks, and volunteers.
6. Recruit volunteers and delegate tasks.
7. Take time to answer the volunteer's technical questions. 
8. Treat the volunteers with respect.


=====
-- kwconder at yahoo dot com

__________________________________________________
Do you Yahoo!?
Y! Web Hosting - Let the expert host your web site
http://webhosting.yahoo.com/


-------------------------------------------------------
This sf.net email is sponsored by: Influence the future 
of Java(TM) technology. Join the Java Community 
Process(SM) (JCP(SM)) program now. 
http://ads.sourceforge.net/cgi-bin/redirect.pl?sunm0004en