[vorbis-dev] who needs documentation?

[volsung at asu.edu]

On Sat, 2 Feb 2002, Graham Mitchell wrote:

> have some actual free time over the coming months.  So I'd like to volunteer 
> my services to write some needed documentation, tutorials, FAQs, etc.

<p>You are awesome.

<p>> On the other hand, I didn't pay enough attention in linear algebra, so I 
> don't remember how to multiply two non-square matrices, much less what a(n) 
> MDCT is.  So API references are probably out.  Also I have no experience with 
> formats other than plain text and HTML, which means man pages, info pages, 
> DocBook or what-have-you would be prohibitively difficult.

<p>Rather than make you waste your time learning a new markup, you could probably
write stuff using simple, traditional HTML markup and convince someone else on
the list ( I volunteer Jack! :) ) convert it to the format we need.

<p>> End-user documentation may be the place for me.  For an example of my "work", 
> see [ http://grahammitchell.net/files/copyrand.txt ], which is the 
> documentation for a utility I wrote for my own use nearly four years ago and 
> subsequently released.

<p>Here are my suggestions (in order of decending importance):

* Update and expand the FAQ on Vorbis.com:

That FAQ is quite stale and could use some updating.  If you decide to do
this, post a request on vorbis at xiph.org for FAQ's (and perhaps answers).  You
can compile the results, clean them up a bit, and send it to Jack.

* An introduction to compressed audio with Vorbis:

Hanging around #vorbis, I can tell you that a lot of people show up with
misconceptions about compressed (especially lossy) audio.  An introduction to
the area which uses Vorbis as the specific example would be a nice thing.  
Most people learned about lossy audio from MP3 and some have assigned
attributes of MP3 to Vorbis incorrectly.  Such a document would also have some
tutorial aspects as well.  If this interests you, I (and many others on the
list) could suggest some topics for inclusion.

(And yes, I would suggest that you not do API documentation.)


---
Stan Seibert

<p>--- >8 ----
List archives:  http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'vorbis-dev-request at xiph.org'
containing only the word 'unsubscribe' in the body.  No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.