Documentation

["Richard G. French" <rfrench(at)wellesley.edu>]

Several postings have hinted at this topic, so I thought I would raise
the issue directly, in the hopes that we might have some effect. David
F., you said not to get you started, and so this is my attempt to get
you started!

What helpful suggestions can we give RSI about its documentation?
Here is my list:

1) Enable help to be read using NETSCAPE.

2) Make sure that ALL the keywords for all procedures are documented. It
is hard to know if undocumented keywords are in the category of "Don't
use this since we reserve the right to change it" or are simply left out
because no one updated the documentation.

3) Math routines that work! In the version of CURVEFIT that was
distributed a couple of years ago, there were so many serious errors
that I had to hack the code all over the place to get it to compute the
parameter errors properly. Just saw the posting on the SVDFIT routine
which also seems to have bugs. I love IDL, but I must admit that I have
gotten to the point where I don't even trust that it computes Bessel
functions properly without doing some cross-checks with other programs.

4) Has someone found a real manual for the GUI builder? If so, I'd love
to read it! I've tried to track it down in the Help menu but just have
not been able to navigate to a manual that actually shows you how to use
the thing, rather than simply telling you that it exists.

5)I would LOVE to have as easy reference for each function a history
list of what changes were made in what version of IDL. I know this is
asking for too much, but it sure would help when trying to figure out
why things that used to work don't work any more!

6)The old DEMO routines in the old days actually did simple things like
draw plots of sine waves in black and white - the kind of thing that a
beginning user would like to know how to do. I used to be able to have
my students learn IDL by running the DEMO and then looking at the code
that produced it. This is no longer possible. The demo is so
high-powered that it is impossible for beginning IDL users to use it as
a way of learning how to program in IDL. I think this is a real loss.
I learned IDL by looking over someone's shoulder and by reading through
programs that did close to what I wanted to do myself. 

That's enough of a list for now - I'm eager to see what others have to
say!

Dick French, IDL site 673 
(OK, David - I bet you have a 1-digit site ID!)
Astronomy Dept
Wellesley College