[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Documentation & Help Desk suggestions



In general I'm very impressed with the quality of the DrScheme
documentation.

These suggestions are from the point of view of someone learning Scheme
outside of a classroom setting (but knowing other languages) with only a
terribly inappropriate Winston/Horn 1984 book (Lisp: second edition) as
a guide. :-) [Yes I know now Scheme and Lisp are very different beasts;
also I had the "History of Programming Languages" ed. Bergin/Gibson
which has a good chapter on Lisp and Scheme.] 

I will buy books on a programming language, but in practice this happens
only after I've spent a few weeks (at least a few days) with the
language first (to see if it is a "keeper"). For example, I bought about
four books on Python after I knew it fairly well, in part to
propagandize it by loaning them out. Two for example are on
semi-permanent loan to a friend. :-) 

The first day or two is a crucial time when you could lose someone just
poking around DrScheme. I put it aside for several months myself after
my first try around March. It might help people like myself to have some
easy on-ramp moving from say a Basic/Pascal/C/Java way of thinking to a
Scheme way of thinking, with point by point equivalent expressions when
possible, or at least contrasting examples of idioms when not. This is
especially true with a language like Scheme, where I was in Barnes&Noble
the other day and didn't find a book on it. :-( [Obviously Amazon stocks
quite a few Scheme books, some by people on this list.]

Actually I've since found some good Scheme tutorials on the web:
  http://www.adelphi.edu/~sbloch/class/272/scheme.shtml
  http://www.acm.org/crossroads/xrds1-2/scheme.html
but it would be nice to have something like this in the Help Desk. 

Things that also might be nice in the Help Desk documentation from that
point of view are:
  * more examples (or perhaps links to usage in a tutorial, such as one
of the above)
  * searches on common programming terms not in Scheme might get a page
with Scheme equivalents. Example, a search on "while" for Keyword or
Index Entry gets no match. It should at least get me a lecture on
recursion! :-)   * likewise when I search on "pascal" or "lisp" or
"Smalltalk" or "Perl" or "Python" I get nothing. (There's some C and C++
links, mostly related to embedding/extending I think.) If Scheme is
currently the underdog (sorry!) it needs to be able to help people make
the transition form whatt they already know.
  * along that line, a general comparison of Scheme to other programming
languages (strengths and weaknesses).

Some other fun links to help people broaden their experience from other
languages to include Scheme:
http://www.math.grin.edu/~stone/events/scheme-workshop/1995/Scheme-vs-Pascal.html
http://www-aig.jpl.nasa.gov/public/home/gat/lisp-study.html

Some of these links I mentioned compare Scheme and Pascal side by side,
which I found helpful, even when it said there was no direct equivalent.

I know there is more information on the Rice web site, but I find:
  http://www.cs.rice.edu/CS/PLT/Publications/
very intimidating. This is in part because I don't easily use all the
file formats. I don't think I've ever used DVI (what is it?) and I have
Ghostscript for PS but usually forget about it, and the fonts look bad
in the version I have. Also there is just so much to wade through there
I don't know where to begin.

So basically, I'm mainly suggesting more hints and propaganda in the
documentation for people coming to Scheme from other languages. Maybe
you could hide these for total novices with a "know other languages"
flag or something if you were worried about confusion. I'd suspect that
some college students might benefit from this material as well, since
many of them probably have had exposure to other languages. 

And, of course, I think there should be a link to this material from the
main page, like "If you know other programming languages..."

Some suggestions of lesser importance related to Help Desk itself:
  * history of pages I've visited recently, ideally in order
  * knowing if I've visited a link or page before by some visual
indicator (link color?) -- i.e. the system is showing to me some of my
depth of understanding and what I have not yet explored
  * an easy way to know what manual the current page is in (perhaps
updating the Help Desk window title?) so I can more easily see the
context of what I am learning. I usually have to burrow up an then
rewind.
  * my own private bookmarks or launch page
  * somehow seeing the URL that goes with a page (important to me when
browsing out onto the web with the Help Desk.)
  * I'm embarrassed to say it, but I didn't notice the search entry
field on the bottom of the Help Desk window the first few days I tried
DrScheme, and I assumed the grayed out menu item at the top meant search
wasn't finished yet. Now I use search all the time and I love it,
especially the way it seperates out hits by manual. But perhaps search
could always be enabled, and maybe somehow popup a dialog or indicate
the edit field below. The first few hours spent with a package can be
crucial, and a search field on an help window is unusual/unexpected for
a Windows user.
  * pointers to instructions on how to build such a cool cross-platform
help desk into my own applications. :-)

In any case, thanks again for the great system. It's already far beyond
most of what is out there, both in quality of code and quality of
documentation.

-Paul Fernhout
Kurtz-Fernhout Software 
=========================================================
Developers of custom software and educational simulations
Creators of the Garden with Insight(TM) garden simulator
http://www.kurtz-fernhout.com