[racket] Getting started with R6RS

Thanks for the detailed feedback! One question, to help put your 
comments in context: can you remember what particular path you took 
through the documentation? In particular, did you hit the "Getting 
Started" page (http://docs.racket-lang.org/getting-started/), and if so, 
where did you go from there?

I suspect that the best "documentation path" for you (given the 
documentation as it is) would have been "Getting Started", then straight 
to the Guide (http://docs.racket-lang.org/guide/), which gets to the 
technical stuff fairly quickly. The "Getting Started" link seems 
missable, though, and I wonder if inlining its contents into the main 
documentation page would have helped.

Ryan


On 05/14/2011 03:20 PM, Elliott Cable wrote:
>[...]
> Neil *exactly nailed* down my experience, in every way, down to the
> exact timing.
>
> Let me expand on that viewpoint a bit for you guys, “from the inside”
> so to speak, give you some of the views that’ve floated through my
> mind as I’ve gone through this process (I’ll get on to my suggestions
> at the end; sorry that this is such a wall-of-text. I just thought
> these thoughts might be valuable input to you guys, a point of view
> you can’t often introspect.):
>
> 1) First off, and most importantly, the obsession with DrScheme is
> *really* off-putting for any serious developer. I know *piles* of
> programming languages, I’ve written hundreds of distinct open-source
> libraries, I know more toolsets than I can even remember; coming from
> a background like that, seeing references to an integrated IDE
> scattered through the *language documentation* itself (as if the IDE
> is a part of the language), is … alienating. 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. 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.
>
> Yes, as Neil wrote above, it *might* have some nice things (I can’t
> speak to that effect myself, as it won’t compile on Lion yet), but
> that’s irrelevant to my point: DrScheme could make me coffee and do my
> laundry for me while I program, and as a newcomer to the language, I
> would *still* be put off by this level of conceptual integration,
> right down to the granular documentation. Whether you like it or not,
> whether they apply to DrScheme or not, there are cultural connotations
> to IDEs, and a lot of veteran programmers want nothing whatsoever to
> do with such a tool. 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*.
>
> 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.
>
> As a “veteran programmer” (again, not trying to make myself sound
> amazing; I’m absolutely sure that every person who’s replied to this
> thread so far is a better programmer than me. I’m just trying to
> present myself as a representative of a particular group; the group of
> those like yourselves and myself, but excluding those who *already*
> know Scheme … that is, the group of those like yourselves who, like
> me, are *currently interested* in learning Scheme.), I didn’t
> appreciate the feeling that the language was hiding something
> important from me (something important enough that it involved
> *competely different* syntaxes after that directive, which obviously
> means the operation of that directive is “kind’uh a big deal.”)
>
> 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; but while
> abstractions like that are great for getting straight to teaching
> beginners about programming without messing about with complex
> discussions of environment and conceptual set-up just to understand a
> small, simple program (à la HtDP), 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.
>
> 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.)
>
> Instead of getting right into the meat of the language, the things I
> cared about learning, the first few links / examples / tutorials were
> all about ‘frivolous’ things, such as creating GUIs or images; nothing
> that was likely to really teach me anything about the language itself.
> Those are the kinds of things you show to beginner programmers, to get
> them motivated to keep learning (Hey! Look! I wrote a *program!* It
> has a *button!*); and that’s fine, everybody needs motivation.
> Unfortunately, a button doesn’t give someone like *me* any motivation;
> we need information on the language semantics. We need to know Why
> This Language is Better™ Than All The Others, and we’re not going to
> get that from ‘yet another GUI toolkit.’ (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)
>
> 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, and what followed was the exact chain of
> thought described by Neil: “so, this is the real specification, and
> Racket is just a divergent implementation, that has some weird system
> that allows me to trigger it to be conformant. Geeze, anybody remember
> Internet Explorer? Really.” As with the above three points, this just
> led to yet more annoyance with Racket itself; and now I had an outlet:
> the mythical “true Scheme.” All I wanted after this was to find a way
> to run R6RS code. I subsequently forgot about Racket, except the
> things I needed to know to drop into “R6RS mode,” and began to dive
> into the R6RS specification (the first time, mind you, in this entire
> debacle, that I felt like I was actually learning a new language,
> instead of jumping through hoops.)
>
> Unrelated note: while, according to Neil and the rest of you, R6RS may
> be a bit of a joke in the Scheme community (I can’t really comment
> yet, honestly) … it has a *wonderfully* well-written specification.
> It’s the best technical specification I’ve ever read. It’s both exact
> *and* a great introduction to the language for someone completely
> unfamiliar with it. Even if R6RS itself is worthless, I certainly
> suggest y’all learn as much as you can from the form and style of that
> specification, and bring it back to Racket’s documentation.
>
>
> … which brings me to my recommendations, after all this, and after
> Neil’s (and other’s) input here: Improve your documentation-path for
> non-beginners.
>
> Of course, it’s a lot more complex than just doing that; but I hope
> everything I’ve shown above will give you some input as to how to do
> so.
>
> 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, and I don’t believe their presence there is in fact
> *helping* anybody. The documentation is too hard to find and too,
> well, “programmer-y” (look at the page; it’s terribly designed, it
> looks like any other technical documentation out there.) 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.
>
> 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, none of the other cruft. 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.
>
> While you’re at it (and I know this is going to raise some hackles,
> but I haven’t pulled any *other* punches in this post, so why start
> now?), remove every single reference to DrScheme along that path
> (except perhaps exactly one, of the form “Racket provides an
> integrated editor and debugger platform for you, if you wish to use
> it!” … but perhaps not even that, as there’s no way of writing
> “integrated editor and debugger platform” or any other mutation of
> that phrase that doesn’t jump out of the page and scream “IDE! IDE!
> Run away!” to most of us by now.) And (yes, more hackles), that path
> includes the landing page. Select a point in the path, far enough into
> the documentation that the average visitor is already going to know
> some basic semantics of Racket, know a bit of the answer to that
> eternal question I posed above (“Why This Language is Better™ Than All
> The Others”); then relegate all mention and coverage of DrScheme to
> *after* that chosen point.
>
> 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. Put some
> rationale in there. While you’re at it, make it easier for people to
> play with ‘pure’ R6RS, even after having told them that that’s a bad
> idea, so they can decide such for themselves.
>
>    [1]: http://mislav.uniqpath.com/poignant-guide/
>    [2]: http://camping.rubyforge.org/
>    [3]: http://hackety-hack.com/
>
> Postscript: I know I’m not making any friends with this post. I’m not
> trying to. A lot of these opinions, and a lot of the suggestions, are
> going to seem offensive from your point of view. That is, in a way, my
> point: your collective points of view, as people already knowing
> Racket/Scheme, are just as invalid in this discussion of a
> non-Schemer’s experience with the Racket website and documentation, as
> would be my own input in a discussion of a general non-programmers. I
> truely hope, reading this post, you can come to understand my mindset
> even if you disagree with the actual arguments made; and that you,
> taking that new understanding, can create better documentation, a
> better initial experience, for Racket. (-:
>
> _________________________________________________
>    For list-related administrative tasks:
>    http://lists.racket-lang.org/listinfo/users