The short summary of this post is: should/could something be added to clarify the purpose of those materials and reassure newcomers who read them.
“Quick: An Introduction to Racket with Pictures”, and HtDP2e “Prologue: How to Program”, are both very nice introductions in the sense of “making the reader aware of”. They cover a lot of material, and the careful selection of examples, and the narrative, are informative without being misleading. Quick says: “This tutorial provides a brief introduction [...]”. Two newcomers [one a programmer, one not] took that to mean it's an “introductory tutorial” in the sense of not just “assuming no familiarity”, but also “some basics to get started”. The two readers misunderstood some of the material, and how much they should understand the material. Without talking to me they might have been put off continuing with racket. They provided feedback about what they had trouble with, but it was based on them having the impression that Quick was something designed more like the HtDP2e Prologue. For the HtDP2e Prologue, the Preface does mention: “Once finished, any beginner is bound to feel simultaneously empowered and overwhelmed.”. But a newcomer with a degree in Philosophy missed or didn't retain that, and read the Prologue even more strongly as “the basics to get started” since it was in a textbook for beginning programmers. She got very far, but was indeed overwhelmed. In particular, she read the Exercises as things she should be able to do as warmups before starting what she assumed was more difficult “serious” material following the Prologue. When she contacted me, I had to assure her that the rest of the book covers the material, more slowly, more completely, in more detail. Including something about why the links to the documentation are there, and what to expect when following them, could also help. Following one of those links at this stage can be even more overwhelming. E.g., Quick's first link to the documentation is “naturally” [to us] for ‘#lang’ . For the Prologue, following a link usually provides more explanation than in the Prologue only in the sense of being complete and precise. To the intended audience of the Prologue, that further explanation is written in unexplained technical notation. -- You received this message because you are subscribed to the Google Groups "Racket Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
