Skip to contentSkip to conversation

Status of ALSA documentation?

DISCUSSION Patrick Shirkey 5 participants 6 messages Feb 15, 2002

lore
Share & tools
lore
#0 lore raw
Quoted 22 lines · --- Paul Davis
Quoted 6 lines

I recently showed a Mac user interested in using Linux for live stage work (no gui needed) the ALSA site so they could get some idea of progress... they just laughed and said there was _nothing_ there to help them evaluate whether ALSA (therefor Linux) was going to be useful to them... well, not within a 5 minute perusal anyway.

i think this is an excellent, critical point.

with ALSA's adoption into the kernel, we have both (1) a chance that more people will write HOWTOs and code but also (2) more people saying "what is it?" and "how do i ....?" the current web site fails completely at both tasks.

as much as i think we are still aiming for uniform operation for all cards (i.e. they just work), i think a good place to start with interface HOWTOs would be to take Dan's soundcard matrix, and add links from each card name to a HOWTO. The default set of HOWTOs can be empty, and we can add to them as time goes on. By empty, what I really mean is a boilerplate document that says "if you have this type of soundcard, just do X, Y, and Z and it will work".

Quoted 3 lines

there should also be a way to collect card-specific bug reports and accessing them all from the HOWTO page.

Very good idea. The alsa-howto can easliy be linked to in this regard. Just needs a slight formatting change and a lot of tedious typing but give me a couple of months and it should be out of the way.

Quoted 6 lines

of course a wiki would be an even better way of collecting card/setup specific quirks, but that seems a bit much to ask for right now.

of course, it becomes critical that the matrix be kept up to date, which could also use a wiki-style input system.

I suggest updating it once every month. Once the bulk is done it should only take about a small amount of work to add new cards. Mostly just copy and paste.

Quoted 6 lines

--p

_______________________________________________
Alsa-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/alsa-devel

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_______________________________________________
Alsa-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/alsa-devel

#1 lore raw

As ALSA is now in the linux kernel, should the HOWTO be part of the linux documents HOWTO pages ?

Cheers
James

Quoted 61 lines

-----Original Message-----
From: [email protected] [mailto:[email protected]]On Behalf Of Patrick Shirkey
Sent: 15 February 2002 07:35
To: Paul Davis
Cc: [email protected]
Subject: Re: [Alsa-devel] Status of ALSA documentation?

Quoted 22 lines · --- Paul Davis
Quoted 6 lines

I recently showed a Mac user interested in using Linux for live stage work (no gui needed) the ALSA site so they could get some idea of progress... they just laughed and said there was _nothing_ there to help them evaluate whether ALSA (therefor Linux) was going to be useful to them... well, not within a 5 minute perusal anyway.

i think this is an excellent, critical point.

with ALSA's adoption into the kernel, we have both (1) a chance that more people will write HOWTOs and code but also (2) more people saying "what is it?" and "how do i ....?" the current web site fails completely at both tasks.

as much as i think we are still aiming for uniform operation for all cards (i.e. they just work), i think a good place to start with interface HOWTOs would be to take Dan's soundcard matrix, and add links from each card name to a HOWTO. The default set of HOWTOs can be empty, and we can add to them as time goes on. By empty, what I really mean is a boilerplate document that says "if you have this type of soundcard, just do X, Y, and Z and it will work".

Quoted 3 lines

there should also be a way to collect card-specific bug reports and accessing them all from the HOWTO page.

Very good idea. The alsa-howto can easliy be linked to in this regard. Just needs a slight formatting change and a lot of tedious typing but give me a couple of months and it should be out of the way.

Quoted 6 lines

of course a wiki would be an even better way of collecting card/setup specific quirks, but that seems a bit much to ask for right now.

of course, it becomes critical that the matrix be kept up to date, which could also use a wiki-style input system.

I suggest updating it once every month. Once the bulk is done it should only take about a small amount of work to add new cards. Mostly just copy and paste.

Quoted 6 lines

--p

_______________________________________________
Alsa-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/alsa-devel

Quoted 7 lines

_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net

_______________________________________________
Alsa-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/alsa-devel

_______________________________________________
Alsa-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/alsa-devel

#2 lore raw
Quoted 2 lines · James Courtier-Dutton

As ALSA is now in the linux kernel, should the HOWTO be part of the linux documents HOWTO pages ?

First of all, the ALSA-sound-mini-HOWTO *is* a part of the Linux
Documentation Project at http://www.linuxdoc.org. Is this what you were referring to?

Next, has anyone contacted the ALSA-sound-mini-HOWTO's maintainer,
Valentijn Sessink? His email address is [email protected]. He's probably the best person to coordinate any changes.

Next, the standard format for the Linux Documentation project is
DocBook/XML. I converted the HOWTO to DocBook/XML back in August of last year. I submitted it to Valentijn but I don't know what happened. I still have my work, if anyone's interested.

<rant>
Finally, if you're going to turn everything over to the Wikki
kiddies then count me out! I believe in quality over quantity. </rant>

-- Kevin Conder, [email protected]

_______________________________________________
Alsa-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/alsa-devel

#3 lore raw
Quoted 4 lines

<rant>
Finally, if you're going to turn everything over to the Wikki
kiddies then count me out! I believe in quality over quantity. </rant>

isn't there a way to limit wiki access? what i like about wiki is the ease of updating it every time something occurs to me. no CVS. it "feels right". just my $0.02.

--p

_______________________________________________
Alsa-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/alsa-devel

#4 lore raw
In reply to Kevin Conder
Quoted 4 lines · Kevin Conder

<rant>
Finally, if you're going to turn everything over to the Wikki
kiddies then count me out! I believe in quality over quantity. </rant>

having written my share of documents, it's not the format that matters; one format can be converted mechanically to another. it's the text. rant all you want about how one format is better than another; but you've demonstrated it best yourself, converting mark rage's document from the wiki to docbook was easier than writing something yourself.

this is why writing docs is non-trivial.

regards,

wingo.

_______________________________________________
Alsa-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/alsa-devel

#5 lore raw
Quoted 8 lines · Andy Wingo
Quoted 4 lines · Kevin Conder

<rant>
Finally, if you're going to turn everything over to the Wikki
kiddies then count me out! I believe in quality over quantity. </rant>

having written my share of documents, it's not the format that matters;

I was unclear, I wasn't talking about format. IMHO, using a Wikki
for technical documentation is misguided. Since it's off-topic, we can discuss this off of the list.

Quoted 3 lines

but you've
demonstrated it best yourself, converting mark rage's document from the wiki to docbook was easier than writing something yourself.

I converted Mark Rage's document to DocBook as a demonstration.
Nobody asked me to re-write it. Was I supposed to?

Too often, Open Source hackers develop NIH (Not-Invented-Here)
Syndrome. You see them do the same work over and over. I try to avoid that, if possible. That's why I have worked with the maintainers of the existing documents like Mark and Valentijn.

I'm dumb-founded by this personal attack... Maintenance work might
be "mechanical" but it's necessary.

-- Kevin Conder, [email protected]

_______________________________________________
Alsa-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/alsa-devel