Re: Documentation & Help Desk suggestions

[Robert Bruce Findler <robby@cs.rice.edu>]

I've put "Teach Yourself Scheme in Fixnum Days" (with Dorai's 
permission, of course!) into our documentation. That should fill this 
gap, I think. It will be out with the next release.

For the time being, you can read it on the web at:

   http://www.cs.rice.edu/~dorai/t-y-scheme/

I've stuck the other comments about the browser on my todo list -- 
not sure when I will be able to get to them, but they are good things 
to do, no doubt.

Thanks for your comments!

Robby

>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