[racket] Getting started with R6RS

20 minutes ago, Elliott Cable wrote:
> [...]

I'll reply to a few points that you raise, and like Robby, I generally
agree with the ones I don't reply to, but for some of them I don't
know what to do.


> 1) First off, and most importantly, the obsession with DrScheme is

DrRacket!  (DrScheme is dead, together with PLT Scheme.)


> [...] seeing references to an integrated IDE scattered through the
> *language documentation* itself (as if the IDE is a part of the
> language), is … alienating.

The language reference is the "Reference" manual.  It's an extensive
piece of text, and the number of references to DrRacket in it is very
small.  (Just grepping through the source, I see around 6 uses of
"DrRacket", most are clearly irrelevant comments that are not
encouraging using it.)  So my guess is that you somehow saw some other
texts which you thought were a reference.

(Even your frequent use of "DrScheme" suggests such a problem, since
the documentation that would revolve around it would have enough
"DrRacket"s to remember...)

So perhaps the problem is that the reference was not clear enough as
such.


> At this point in my exploration of Racket (first five minutes to an
> hour or so), I hadn’t yet written off the language, exactly, but I
> was certainly having the seeds of doing so sowed by this.

Pointing at them could be helpful.


> Hell, on my first visit to the front page, I was seeing that every
> single code snippet in the rotating presentation had to repeatedly
> inform me that I could execute that snippet via an IDE.

You probably skimmed through the explanation blurb quickly and got
hung up on the mention of DrRacket.  To clarify, letting people run
things in DrRacket ensures that we can anticipate their experience,
but many of the examples run outside of DrRacket just as well.  For
these, the blurb says:

  To run the example, install Racket, start DrRacket, paste the
  example program into the top area in DrRacket, and click the Run
  button. >>> Alternatively, save the program to a file and run racket
  on the file. <<<

My guess is that for you, swapping the order of the two sentences
would be better -- as someone with a justifiable short attention span
(justifiable since you're reading stuff on a web page) who wants to
get the "real" experience first.  Unfortunately, I don't see a good
way around this, since by far most people benefit from the current
order (ie, a combination of the same short attention span with
extremel cluelessness for anything that has the form of a command-line
use).

BTW, most of the front page examples have that blurb, but there are a
few (gui and/or graphics examples) that require racket (also possible
to run in different way, but will require much more explanationage),
and there's one that requires just racket.  Perhaps you have ideas for
more examples that fall in that last category.  (They're hard to come
by, since usually it is better to go with the above blurb.)


> (I can’t speak to that effect myself, as it won’t compile on Lion
> yet),

IIUC, Lion is still just a beta release thing, so viewing the world
that is accessible via it is kind of expected to have such problems,
no?


> I would *still* be put off by this level of conceptual integration,
> right down to the granular documentation.

Again, there shouldn't be DrRacket references in the actual reference
other for DrRacket's manual, or manuals for DrRacket tools etc.
Pointing to bad references would be helpful.


> If DrScheme is really such a great thing, then you should be
> pipelining developers to it *through* Racket: show them that Racket,
> alone, is amazing, and *then* show them that DrScheme can make
> development in Racket *even better*.

That's another case where you're very different from the average
newbie.  Most newbies that I've seen have problems starting a terminal
and typing the full path to the racket executable.  So just going by
the numbers, going with the drracket-first is more effective.  We
could probably use some help finding the right hooks that will make it
cater better to people like yourself (there are some, which I'll talk
about below, but probably not enough).


> 2) The whole “languages” thing is nearly as off-putting as the
> DrScheme obsession, but in a different way. When I come across an
> instruction saying to add `#lang racket` or `#!r6rs` at the top of the
> file, with no explanation of what that does, it feels more than a
> little bit too much like “magic.” It feels like the language trying to
> pussyfoot around inexperienced developers, hide from me operation that
> is considered ‘too complex’ for me to understand.

WRT this complaint, I really don't see any sane way of not showing it
as a magical thing.  To fully understand the role of `#lang' you need
to know about controlling the reader, writing macros, low level
language reflection APIs etc.  Any explanation that will do that is
likely to be completely irrelevant and *damaging* to 95% of the
newbies who will read it.

For example, you were confused by a mention of `#%module-begin' -- it
would be better to hide it from you so you don't get those kind of
problems so early.  (And IIUC, Matthew said that he'll do just that.)
You are, of course, a very irregular case since it seems that you were
intentionally looking for those things, and again, IME, almost no
newbie does.

BTW, that's nothing new -- the details of how `#lang' works are parts
of the low level implementation, and *many* languages won't jump
straight to implementation notes.


> [...] Thus, my next step was to attempt to figure out exactly what
> was being ‘hidden’ from me, what those directives *actually
> did*. Luckily, that didn’t take too long once I knew what I was
> looking for;

OK, so it isn't hidden well enough that you couldn't find it.  IMO,
this is actually a good point about the documentation -- it is exactly
trying to do that: avoid discussing the mechanics of `#lang', yet make
it easy to find if you really want to.  My own conclusion here is that
you've let your experience trip you: you probably saw those attempts
to hide how `#lang' works and thought to yourself that you're
experienced enough that you don't need such babysitting.  If this was
a different language, this could be compared to immediately looking at
the dissassembly of a function to learn how arithmetics is done.  But
for some reason, doing something like that is "clearly insane",
whereas doing that for `#lang' seems better...


> they’re really not at all so great for somebody like me, who expects
> to understand every line of the first source-code file he’s writing
> in a language that is new to him, as he writes them.

The main thing that I think was a failure here is to understand that
Racket is truly a multilingual environment that allows different
languages to co-exist.  With that view there is nothing wrong with
presenting it as a kind of a magic -- it serves a *very* similar
purpose to something that is known as "magic numbers"!


> 3) After the issues described above, I realized that the
> ‘documentation path’ I’d been following just wasn’t *for* me.
> Looking around with a little bit more descerning eye, I realized
> that all the documentation I could find seemed to be for
> children. (Don’t misunderstand me; I’m not using that as an
> insult. I mean, quite literally, the documentation seemed to be of
> very similar form to the “teen-specific” books and tutorials that I
> had seen people passing around for other languages like Ruby and
> JavaScript.)

My guess is that you've ran into the "Quick" guide:
http://docs.racket-lang.org/quick/ -- is this correct?  If there are
other such things then please point them out.

If you did, then, to make another guess, you would benefit much more
from the "More" guide: http://docs.racket-lang.org/more/ which is much
more tool/command-line/server oriented.  (And also the main guide,
http://docs.racket-lang.org/guide/ , which would probably work better
than just a reference.)  If this is the case, then again, I don't see
much to do, since they're both listed right next to each other.


> [...] (Again, just as with #1, I was accosted with this mindset with
> my very first visit to the homepage, before I even knew what Racket
> was: the first code example I saw was something to do with creating
> images or a window or something; I immediately flipped through them,
> looking for something more relevant that would give me a better
> taste of the language)

Given that there *are* such examples there, it would be interesting to
learn how you missed them.


> 4) Finally, this has already been discussed a bit above, but I
> thought I’d make sure I included it in this list: after my troubles
> with finding any sane tutorial-style introduction to the “meat” of
> the language, I decided the next best step would be to go straight
> to the specification. Of course, in looking for a Racket
> specification, I found the R6RS specification, [...]

Yes, that's a common problem.  Part of the reason for the name change
was to discourage such misconception as "to learn about PLT Scheme you
need to learn about Scheme".


> [...] Geeze, anybody remember Internet Explorer? Really.” [...] the
> mythical “true Scheme.”

... as well as the much weaker role that the "Scheme Standard", or
even just "Scheme" plays in actual Scheme implementation.  (Though
that problem is on a larger scope that is not relevant here.)


> Unrelated note: while, according to Neil and the rest of you, R6RS may
> be a bit of a joke

[More like a sad fable.]


> it has a *wonderfully* well-written specification.

That too suggests to me that you missed the reference manual
(http://docs.racket-lang.org/reference), since it's written in a very
similar style.


> For instance, I’m biased, of course, but I really think all of this
> beginner introduction content, the HtDP-derived things, should be
> moved elsewhere. They’re out of place right in the language’s
> official documentation,

"HtDP-derived things" should also not be mentioned in the main
reference, so pointers will help.


> (look at the page; it’s terribly designed, it looks like any other
> technical documentation out there.)

Which one?


> Create a seperate site, something like [the][1] [obvious][2]
> [examples][3] from the Ruby world; hire or otherwise rope a *good
> designer* into making it “flow” for the newcomer, and make *that*
> the central hub for newcomers to programming in general and
> teens. That’ll help expose them to DrRacket and Racket, and
> programming things like this in general; it’s a great start.

While we didn't use a proper designer for it, the current presentation
is the result of years of following how people get into the language.
I can definitely say that people are almost always coming from a very
different perspective.  (Even experienced ones -- and my guess to that
is that you somehow managed to look at the wrong pages, as I mentioned
above.)


> Then, provide a clear documentation path, right from
> http://racket-lang.org/ and ending in an actual technical
> specification, that caters to programmers who simply want to learn
> “Racket Scheme”, the language,

(Racket is not Scheme!)


> none of the other cruft.

Again, pointers at what you'd consider as "cruft" would be helpful.
(By pointers I mean links on pages that go to the cruft, and why they
shouldn't be there or how they should be worded differently.  I'm not
talking about the cruft itself, for example, my guess is that you're
considering htdp.org as such, but that won't help.)

(BTW, another gentle suggestion -- htdp.org can be much more useful to
you than you'd think on a first impression.)


> Make sure that path has them buried in lingual semantics and syntax
> as quickly as possible, make sure it gets them writing code into a
> text editor and running it on their command line (of which I
> guarantee you they already at least four open) As soon As Possible.

Burrying people in "lingual semantics" seems like a horrible way to
treat newcomers!  In fact, we frequently get such complaints from
people who stumble onto the reference prematurely.


> [...] answer to that eternal question I posed above (“Why This
> Language is Better™ Than All The Others”);

Yes, that's still under debate -- how to write something like that.


> Finally, relatively minor to the other suggestions … somewhere, as
> soon as it’s fesible in aforementioned documentation-path, mention the
> R6RS specification, and explain *why* it’s not followed.

(That would be much harder than you think, and an attempt at doing
that is the name -- it's not "Scheme".)


> Postscript: [...] A lot of these opinions, and a lot of the
> suggestions, are going to seem offensive from your point of
> view.

Counter postscript: my guess is that you'll take some of my questions
and suggestions as flaming.  Bear in ming that absolutely no flames
are intended.  I'm just trying to find out exactly the places that
could improve and the ways in which they could be improved, and at the
same time, I see some things that indicate that you've missed some of
the content that you should have read.

(Re the links to those things, we know about such things...)

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!