more improvement of alsa web pages

more improvement of alsa web pages

[Takashi Iwai]

Hi,

first of all, kudos to Patrick;  the new appearance is really good!


now i have a proposal.

how about to add informational pages for each driver, and make links
from soundcard matrix?  then a user can reach to the detailed info by
two clicks from the top page.

a driver page will contain:

- supported and tested hardwares

- detailed description, including module parameters and
  supported/unsupported features

- known bugs (and workarounds if any), TODO

- links to other resources, such as howto's


the pages should be controlled by cvs, so that both developers and web
admins can keep them up-to-date.
an advantage is that we can generated documents for
alsa-kernel/Documentation from these files.

i'm not sure whether these docs to be auto-generated or should be
static files.  also, we need to discuss which format is best - sgml,
docbook, html or else.

we can start from converting existing docs (e.g. CMIPCI.txt) to
such pages.


any comments please?


Takashi

Re: more improvement of alsa web pages

[Paul Davis]

>how about to add informational pages for each driver, and make links
>from soundcard matrix?  then a user can reach to the detailed info by
>two clicks from the top page.
>
>a driver page will contain:
  
 [ ... ]
 
>the pages should be controlled by cvs, so that both developers and web
>admins can keep them up-to-date.
>an advantage is that we can generated documents for
>alsa-kernel/Documentation from these files.
>
>i'm not sure whether these docs to be auto-generated or should be
>static files.  also, we need to discuss which format is best - sgml,
>docbook, html or else.
>
>we can start from converting existing docs (e.g. CMIPCI.txt) to
>such pages.
>
>
>any comments please?

we had quite a bit of discussion about this a month or two back. some
people were in favor of something like a wiki, where people could add
information in a dynamic, immediate way, and thus increasing the
likelihood that we'd accumulate a bunch of useful information. others
wanted something more like you're suggesting.

i think that its important that there is a mechanism to make
collecting information from users extremely easy, because otherwise
there simply won't be very much in this pages. CVS doesn't meet this
requirement since its intended to grant write access to a relatively
small number of people (and certainly not just anybody who happens to
have a useful piece of info about their audio interface).

patrick even mocked up a sample page which i critiqued in a number of
ways. 

whatever we do, we should move forward with this fairly quickly,
because its one of the biggest weaknesses (after the complete lack of
user-usable documentation for ~/.asoundrc) of ALSA at this time.

--p

Re: more improvement of alsa web pages

[Patrick Shirkey]

--- Takashi Iwai <tiwai@suse.de> wrote:
>Hi,
>
>first of all, kudos to Patrick;  the new appearance is really good!
>

Thanks.

>
>now i have a proposal.
>
>how about to add informational pages for each driver, and make links
>from soundcard matrix?  then a user can reach to the detailed info by
>two clicks from the top page.
>

It's a good idea which we discussed when people were working on the howto wiki a couple of months back.

>a driver page will contain:
>
>- supported and tested hardwares
>
>- detailed description, including module parameters and
>  supported/unsupported features
>
>- known bugs (and workarounds if any), TODO
>
>- links to other resources, such as howto's
>
>
>the pages should be controlled by cvs, so that both developers and web
>admins can keep them up-to-date.
>an advantage is that we can generated documents for
>alsa-kernel/Documentation from these files.
>
>i'm not sure whether these docs to be auto-generated or should be
>static files.  also, we need to discuss which format is best - sgml,
>docbook, html or else.
>
>we can start from converting existing docs (e.g. CMIPCI.txt) to
>such pages.
>
>
>any comments please?
>

I can draft a template page in html over the next few days. Keeping in line with the new format style.


--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/



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

_____________________________________________________________
Run a small business? Then you need professional email like you@yourbiz.com from Everyone.net  http://www.everyone.net?tag

Re: more improvement of alsa web pages

[Takashi Iwai]

At Wed, 24 Apr 2002 08:29:44 -0400,
Paul Davis wrote:
> 
> >how about to add informational pages for each driver, and make links
> >from soundcard matrix?  then a user can reach to the detailed info by
> >two clicks from the top page.
> >
> >a driver page will contain:
>   
>  [ ... ]
>  
> >the pages should be controlled by cvs, so that both developers and web
> >admins can keep them up-to-date.
> >an advantage is that we can generated documents for
> >alsa-kernel/Documentation from these files.
> >
> >i'm not sure whether these docs to be auto-generated or should be
> >static files.  also, we need to discuss which format is best - sgml,
> >docbook, html or else.
> >
> >we can start from converting existing docs (e.g. CMIPCI.txt) to
> >such pages.
> >
> >
> >any comments please?
> 
> we had quite a bit of discussion about this a month or two back. some
> people were in favor of something like a wiki, where people could add
> information in a dynamic, immediate way, and thus increasing the
> likelihood that we'd accumulate a bunch of useful information. others
> wanted something more like you're suggesting.
 
ah, i remember the thread, too.


> i think that its important that there is a mechanism to make
> collecting information from users extremely easy, because otherwise
> there simply won't be very much in this pages. CVS doesn't meet this
> requirement since its intended to grant write access to a relatively
> small number of people (and certainly not just anybody who happens to
> have a useful piece of info about their audio interface).

yes, feedbacks from users are very important.  however, i am
suspicious to give any possibility for arbitrary users to write / 
update the contents.  i prefer a non-interactive system with
moderators (or editors) to keep the quality and consistency of
contents (please remember that i think of documents to be put in the
kernel tree, too).  moderators receive a page source (e.g. wiki) from
users and put it to the web.

for quick reaction to the new info, we can have an e-mail account
which notifies the mails to all moderators, so that it's updated asap
by one of them.  in the above i suggested cvs only as a method to keep
the page sources and solve the confliction between moderators for
updates.


> patrick even mocked up a sample page which i critiqued in a number of
> ways. 
> 
> whatever we do, we should move forward with this fairly quickly,
> because its one of the biggest weaknesses (after the complete lack of
> user-usable documentation for ~/.asoundrc) of ALSA at this time.

yeah, exactly..


Takashi

Re: more improvement of alsa web pages

[Takashi Iwai]

At Wed, 24 Apr 2002 05:46:07 -0700 (PDT),
Patrick Shirkey wrote:
> 
> I can draft a template page in html over the next few days. Keeping
> in line with the new format style.

do you write a bared html or is it generated from a meta format?


Takashi

Re: more improvement of alsa web pages

[Patrick Shirkey]

--- Takashi Iwai <tiwai@suse.de> wrote:
>At Wed, 24 Apr 2002 05:46:07 -0700 (PDT),
>Patrick Shirkey wrote:
>> 
>> I can draft a template page in html over the next few days. Keeping
>> in line with the new format style.
>
>do you write a bared html or is it generated from a meta format?
>

Firstly, why?

I write it all myself because I don't know or trust auto generators much.

>From what I've seen they often have *a lot* of extra crud which makes things difficult to change.

Of course that also means I have to be careful about formatting or I can end up confusing things even more as Paul encountered recently ;)

--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur
Http://www.boosthardware.com
Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/




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

_____________________________________________________________
Run a small business? Then you need professional email like you@yourbiz.com from Everyone.net  http://www.everyone.net?tag