Re: PLEASE improve the ALSA documentation!

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



At Sat, 16 Dec 2006 20:55:51 +0100,
Ingo Müller wrote:
> 
> PLEASE improve the ALSA documentation!
> 
> To many users (myself included), this is the most important thing of any
> software application!
> 
> Last week, I spent two and a half days to configure Alsa, which I'd now
> be capable to do in less than 30 minutes and anyone with a little
> experience with Linux should be able to do in less than one hour. The
> problem isn't (like I thought first), that Alsa is not capable of doing
> the things I wanted to, or at least not in a clean way. The truth is,
> I'm really impressed by all that can be done and how simple it in fact
> is. The real problem is, that nobody tells you how to do it!
> 
> In order to change that, I'll try to describe precisely what problems I
> had and - more important - how I think they could have been avoided:
> 
> 1) When I started to get my sound to work, I didn't know a lot about
> Alsa yet. But I stumbled upon your website quite early. Unfortunately,
> it was almost completely useless for me at the beginning. I was missing
> an explanation of the very basics. "Efficient support", "modularized",
> "thread-safe design" mean nothing to an unexperienced user like me. What
> would have helped might have been: "Alsa is a piece of software that
> connects applications playing sound to the hardware sound cards by
> providing them a universal interface. It includes the drivers for almost
> every sound card available and is compatible with most applications,
> even those using Alsa's predecessor OSS." If I had known that, I
> would've been sure I was looking for a solution in the right place. But
> this simple explanation was just missing (or hidden very well).

Yeah, these texts are really outdated.  It's a situation of a decade
ago.

> 2) The separation of the site into users, developers and hardware
> manufacturers makes a lot of sense. What I found in the user section was
> not always helpful, though. For example, I think that "Background info"
> is not the first thing a new user is interested in. The "Alsa soundcard
> matrix" could be improved, too. In my opinion, the most crucial thing is
> missing: "This is a list of supported sound cards. It shows which kernel
> module has to be used for your hardware." The ALSA wiki is quite ok, but
> the information is distributed in many subcategries. Users are missing
> an introduction telling them: They have to install Alsa first. Then
> configure Alsa. Then configure the applications. They need to know that
> their distribution most likely did the first thing, and probably the
> second, too. How we can check whether those things have been already
> done? What possibilities do we have for the configuration and how and
> why do we have to configure applications. That introduction should give
> users a good overview about the problematic and lead them to places
> where the different steps are explained in detail.

In general, we really need someone who can update the web pages.
Or, as I already suggested, we should move to Wiki and let
volunteering users updating the all information...

> 3) The problem I had to deal with the most: the .asoundrc file. I did
> see the available documentation of that file on alsa-projects.org, but
> only because I was lucky enough to find it on google instead of it being
> linked to on the Alsa home page like I think I should be. Having found
> that page, it was still difficult to understand the purpose of that
> file. What would have helped would have been a brief overview of what
> I'm able to do with that file, an explanation of the purpose and some
> definitions or helpful tips. For example: "In the .asoundrc file, you
> define virtual interfaces that applications can connect to. Every
> interface modifies the sound stream in some way and then passes it on to
> its slave, either another virtual interface or an hardware sound card."

Well, the best situation would be that users don't have to touch
asoundrc at all.  I think it's already so in most cases.  So, what you
described about is the documentation for advanced (or adventurous)
users.  This should be combined in a single place with glossary and
tutorials.


> 4) I admit that most of the necessary information is somewhere out
> there. Otherwise my soundcard would still not work at all, right?  :-)
> The problem is that it is splattered all over the internet and consist
> mostly of examples. Therefore, a user who is new to Alsa has to search
> endlessly end then analyse the examples, understanding only bits of each
> of them, "reverse engineering" those examples, and then try and solve
> his own problems. I think that reverse engineering is something that
> shouldn't need to be done with open source software. In my vision of a
> good documented project, a new user would find the project's homepage on
> google (maybe indirectly), understand his problem with the help of the
> documentation and hopefully also find a standard solution there. If not,
> he might find a similar problem being discussed in the included forum,
> just like everything else concerning the project (instead of in many
> different places), or at least be able to ask for help there. He would
> not need to leave the projects page, unless he gets general or
> distribution specific problems (for example, if he doesn't know how to
> compile the kernel).

Right, the installation instruction should be on web, too.

> All that leads to one conlcusion: The documentation of Alsa has to be
> improved and maybe even redone! And it has to be on the offical site of
> the project and (at least partially) by those who know what they are
> talking about. But (and this is the tricky part) it should be
> understandable by most people who have some experience with Linux. I am
> willing to help with making it understandable for the users, but I
> wouldn't really know where to start, if I was to write documentation
> from scratch. English is not my first language, so I would need some
> help with that too.
> 
> Please show me that you, the creators and developpers of Alsa, feel the
> need of improvement of the documentation of your project, in order to
> make it usuable for everyone, not limiting it to an elitist group of
> specialists, and support (activly as good as you can) the work on the
> documentation done by users who want to help although they might not be
> Alsa experts.
> If I get enough support on this part of the Alsa project, if my work is
> welcome and completed (reviewed, corrected...) by Alsa developers, I am
> willing to spend a quite big amount of time implementing my suggestions.
> 
> Thanks in advance and greets, Ingo

Honestly, I also don't know where to start.  Actually, I have little
time to spend for documentation.  But some images are in my mind,
too...   We need to cover different areas like below:

1. Really basic information, download, installation, and setup of the
   system on major distros

2. Support status for each card, and troubleshooting/FAQ

3. Advanced usage - architectural overview, asoundrc stuff

4. Programming information - API, etc

Each of these categories need fairly different frameworks for
documentation.  For example, 4 could include the auto-generated
doxygen texts while 1 should be written really understandablly.

> PS: I just read about a conference where audio on Linux was a main
> subject. It seems that not only users have problems on that topic.
> "Audio on Linux sucks. Developers don't know which interface to use."
> (http://developer.osdl.org/dev/desktop_architects/index.php/Desktop_Architects_Meeting-39)
> That's nothing I can do about at all and it may even not concern Alsa.
> But it shows that documentation is something that has to be worked on!

Well, "XXX sucks" is the most frequently used sentense in year 2006
(look at OLS presentations, for example ;)


Takashi

-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys - and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Alsa-devel mailing list
Alsa-devel@xxxxxxxxxxxxxxxxxxxxx
https://lists.sourceforge.net/lists/listinfo/alsa-devel


[Index of Archives]     [ALSA User]     [Linux Audio Users]     [Kernel Archive]     [Asterisk PBX]     [Photo Sharing]     [Linux Sound]     [Video 4 Linux]     [Gimp]     [Yosemite News]

  Powered by Linux