In the course of reacquainting myself with Csound, I’ve been grumbling about the state of the documentation. Now, grumbling is one of my favorite pastimes. But there’s seldom any shortage of stuff to grumble about. Here’s an excerpt from a message I just posted to the Csound list, in response to some comments that another Csounder made:
I basically agree with your characterization of Csound. And I totally agree that work (lots of work) will be required for anyone to master it.
But there are other factors rambling along in the back of my mind, which perhaps I should make explicit.
First, I’m a big supporter of making cool tools available to musicians, and free tools especially. Most musicians are poor! A system that lets people do sophisticated things without spending piles of money is something I feel EVERY musician who uses a computer needs to know about.
Second, the Csound documentation is not as clear or explanatory as it could or should be. Now, I understand that all of the docs are prepared by unpaid volunteers, and that one shouldn’t look a gift horse in the mouth. But if a musician gives up in bafflement because some feature of Csound (or more likely, five or six features) wasn’t explained clearly, we all lose. The Csound community loses that musician, and his or her potential audience loses the experience of some cool music that will never get recorded.
Yes, there are things that the Csound community could do to make the journey of a newbie smoother, but I don’t feel that it will ever be easy. The info is out there if a person wants to learn it. When the pupil is ready, the teacher will arise.
There are a lot of young people who can’t afford to attend “public” universities in California (where I happen to live), or who can’t get the classes they need in order to graduate due to budget cutbacks, who would say that that assertion is rather naive.
Also, I’m sensitive on this subject because I’ve been writing and editing how-to material for musicians who use synthesizers for the past 30 years. When I look at the Csound manual’s page on Real-time MIDI Support, for instance: (a) It never mentions using the GUI as an option, only the command line, and (b) the words “buffer” and “latency” are never used. That being the case, I would not characterize this page as providing a sufficient discussion of the topic. I’m speaking not as a baffled musician (though I’m sometimes in that category) but as a professional editor.
In the past year or two I’ve done a fair amount of hobbyist programming of text-based games using a system called TADS 3. The TADS author community is at least one order of magnitude smaller than the Csound user community, and very likely two or three orders of magnitude smaller. If there are more than fifty active TADS 3 programmers in the world, I’d be shocked. Yet the TADS documentation … well, it’s not perfect (and TADS users will tell you I like to kvetch about it), but it’s much more thorough and readable than the Csound documentation.
I suspect one important reason why that’s the case is that the TADS community, like the world at large, consists primarily of Windows and Mac users. The Csound community, in contrast, is overbalanced in the direction of Unix/Linux users. Unix/Linux users are, by and large, extremely computer-literate and used to figuring stuff out for themselves. Mac and Windows users are not. I suspect (though I can’t prove it) that the state of the Csound documentation more closely reflects the attitudes and expectations of the Unix/Linux community.
It’s a theory, anyhow. Maybe I’m entirely wrong. As always, YMMV.