Subject: [linux-audio-dev] Rant about bad documentation.
From: Kevin Conder (kconder_AT_interaccess.com)
Date: Tue Oct 02 2001 - 18:55:02 EEST
I saw this note on the Csound mailing list and thought I'd forward
it here. I agree with the point that poorly documented programs are harder
to use.
Note: I am Kevin Conder in Chicago and this is Kevin Parks in
Seoul, Korea. I took the liberty of adding some paragraph breaks to his
remarks...
-- kevin [Conder] at kevindumpscore dot com
---------- Forwarded message ----------
Date: Tue, 02 Oct 2001 21:00:56 +0900
From: kevin parks <cpsoct_AT_lycos.com>
Reply-To: csound_AT_lists.bath.ac.uk, cpsoct_AT_lycos.com
To: csound_AT_lists.bath.ac.uk
Subject: Re: [Csnd] Pmask manual [rant]
yes, a manual and tutorial would be really nice. The lack of documentation
is one reason why i have given up on Pmask, despite the fact that i use
python almost daily. In order to have the benifits and extensibility of
python, user-friendliness was obliterated in pmask. Without a manual and
tutorial i doubt many people will be able to make the jump from cmask,
which one could learn to use in a couple of hours.
I am grateful that pmask exists, but i am really still not able to make
heads or tails of it. Just installing the package was difficult and
troublesome. The fact that there is still so much interest in Cmask (and
pmask) and so few people using pmask indicates that a user's guide is
sorely needed. Unless you just made pmask for yourself to use, which is
cool.
That is how computer music is going these days. People are doing their
best to make make sure people without a Ph.D in computer science are
completely lost. Look at SuperCollider. Revolutionary, powerful, cheap
even (but not free), but almost completely unlearnable to anyone who is
not a wicked ass computer geek.
The author tries his best to keep it that way too it seems, as the docs
are worse now than the were in SC 1.x. The guy can write a ugen that makes
you coffee but can't sit down for a while an write a manual that can help
musicians use his programs.
That is why i will always love Dr. B. As far a i know, they guy has never
written a Ugen. He makes all kinds of requests, etc. But his tutorials are
worth 100 Ugens. Every time one of my students asks me how to get started
in Csound, i give them the Dr. B toots and they are off an running.
Chris Dobrian tool. You want to know what Max is so popular? even though
it is way overpriced at $500!? The freakin manuals are awesome! That is
why! and so is the built-in help!
Developers!!!! PLEASE WRITE DOCUMENTATION!!!! OTHERWISE WE CANNOT USE YOUR
PROGRAMS!!!!!!!!!!
best,
kevin parks
seoul, korea
This archive was generated by hypermail 2b28 : Tue Oct 02 2001 - 18:51:30 EEST