Skip to contentSkip to conversation

ALSA documentation project?

DISCUSSION Kevin Conder 3 participants 4 messages Oct 25, 2002 – Oct 28, 2002 1 message not in the archive

lore
Share & tools
lore

A message that is not in the archive (sent off-list or not yet received): [email protected]

#1 lore raw
Quoted 2 lines · Abramo Bagnara

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

#2 lore raw
Quoted 3 lines · Kevin Conder
Quoted 2 lines · Abramo Bagnara

Documentation has not been written for lack of funding and lack of volunteers.

Maybe Abramo meant "funded volunteers" ? Maybe not, but then with one short response like that it's a bit hard to tell.

Quoted 1 line

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

I, and I'm sure a _lot_ of other people, are just as frustrated as hell with the state of ALSA. It's Ok for those with the time and dedication to dig deep and hard but for the "rest of us" it's generally been a right royal pain dealing with ALSA.

Two points to consider: I set up that Wiki from similar levels of frustration with the lack of documentation and you are more than welcome to leave ANY input on that server... also, I feel, one of the main obsticles holding back even wider adoption of ALSA is the lack of not only documentation (Patrick Shirkey has done a great job of plugging holes) but the difficulty of the non-English speaking core developers struggling to relate to the rest of us via these lists. It's almost a non-event beyond purely tech/code issues.

Jaraslov, Abramo and Takashi... you guys pump bigtime at keeping the codebase and ALSA rolling along but there is a distinct lack of leadership and direction... most likely because of the language barriers, I presume. I am not slagging on you 3 guys and I do not know what the right answers are but I can see that no one in any leadership capacity is actively outlining any coordination and direction "for the rest of us".

--markc

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

#3 lore raw

At Mon, 28 Oct 2002 21:04:45 +1000,

Quoted 11 lines · Mark Constable

Two points to consider: I set up that Wiki from similar levels of frustration with the lack of documentation and you are more than welcome to leave ANY input on that server... also, I feel, one of the main obsticles holding back even wider adoption of ALSA is the lack of not only documentation (Patrick Shirkey has done a great job of plugging holes) but the difficulty of the non-English speaking core developers struggling to relate to the rest of us via these lists. It's almost a non-event beyond purely tech/code issues.

that's true. for me, writing documentation means that it costs far longer time than writing codes although the output quality would be worse.
(well, the real reason is that we (at least i) are "geeks" and love
to write codes but not documents :)

Takashi

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

#4 lore raw
In reply to Kevin Conder

At Thu, 24 Oct 2002 23:16:06 -0700 (PDT),

Quoted 11 lines · Kevin Conder
Quoted 2 lines · Abramo Bagnara

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.

Quoted 4 lines

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.

oh, please don't take such an answer seriously. and i would apologize if it were me (i don't remember it, though).

but, one thing is also true - one will get better answers on a ML than writing directly to the personal address, because the questions and answers are reviewed publicly and eventually there will be better chances that other people are involved.
such a discussion should be on alsa-docs ML, not alsa-users, though.

Quoted 3 lines

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!

no, alsa-doc cvs tree itself exists, so it's not thrown out. well, it's true that the old documents are no longer valid, because of so many changes since the time of 0.5.x.

Quoted 9 lines

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.

agreed.
if you (and other people) still have interest, we can create a new ML for documentation (and open a cvs tree if necessary), as we did before.

Quoted 1 line

4. Never switch documentation standards without discussing it first.

i don't believe this will happen again.
(iirc, there were discussions about this change. but this was
perhaps only on alsa-devel ML.)

Quoted 3 lines

5. Put a responsible person in charge of coordinating the submissions, tasks, and volunteers.
6. Recruit volunteers and delegate tasks.

i would like to take this job, but, i myself will have little time to write actually something.

Quoted 2 lines

7. Take time to answer the volunteer's technical questions.
8. Treat the volunteers with respect.

yes, that's a must.

ciao,

Takashi

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