You are of course right that the term “exercise” doesn't appear where I thought it did, and I should have double-checked. The person reading the Prologue referred to these as exercises:
“Before you read on, ponder the following changes to your program: [...] Better than pondering is doing. It’s the only way to learn. So don’t let us stop you. Just do it.” Earlier in the Prologue it says: “And now you’re ready to write programs that make rockets fly.” As for the links to BSL documentation: if a reader clicks on one of the links then I'd like to consider why they clicked. If it's because they're unsure about something and see, e.g., ‘(+ x y z ...) → number’, they're unlikely to feel more informed or be reassured. I'll follow up with proposals, all of which will likely be small notes/reminders about the spirit of the Prologue, in certain key places. In other words, yes, weaving in the explanations you provided for me in your response. On Monday, 10 April 2017 12:27:33 UTC-4, Matthias Felleisen wrote: > To start with, thank you for pointing out hurdles for “beginners” or “people > new to Racket.” We listen and we want to improve this material so that > everyone can design programs (either Racket or BSL). > > Let me speak to HtDP/2e because I am responsible for it. I will let Matthew > speak to Quick. > > — I do not know how to address your comment about exercises because the > Prologue does not contain any. There is a link to an exercise way into the > weeds for exactly the one link that is complicated. > > — I followed many links from the Prologue to the Docs. There is one > overwhelming link: the one to animate. But given the context, I don’t > understand why anyone would even want more documentation. The book itself > spells out what the function does. Yes, in some sense this is complicated > because functions on functions are nothing that people encounter. My hope is > that students copy and paste this expression into DrRacket and see a rocket > fly. Hello world. > > — I really do not expect more than ‘read and copy and play and feel somewhat > confused.’ That’s why I announce it in the Preface. > > — I also wrap up the Prologue with “You are not a programmer. Let’s get > started.” > > POSSIBLE ACTIONS: > > — I could try to turn the links off in the Prologue. But I want to get > students in the mind set — look at the docs — because programmers must learn > to look at docs. Unless they want to stay Stackoverflow coders. > > — I could try to weave in another warning into the Prologue that this is > meant to be read quickly in the above spirit. > > — Do you have any other proposals? > > > > > > > > > > On Apr 9, 2017, at 2:45 PM, gfb <g...@cs.toronto.edu> wrote: > > > > 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. On Monday, 10 April 2017 12:27:33 UTC-4, Matthias Felleisen wrote: > To start with, thank you for pointing out hurdles for “beginners” or “people > new to Racket.” We listen and we want to improve this material so that > everyone can design programs (either Racket or BSL). > > Let me speak to HtDP/2e because I am responsible for it. I will let Matthew > speak to Quick. > > — I do not know how to address your comment about exercises because the > Prologue does not contain any. There is a link to an exercise way into the > weeds for exactly the one link that is complicated. > > — I followed many links from the Prologue to the Docs. There is one > overwhelming link: the one to animate. But given the context, I don’t > understand why anyone would even want more documentation. The book itself > spells out what the function does. Yes, in some sense this is complicated > because functions on functions are nothing that people encounter. My hope is > that students copy and paste this expression into DrRacket and see a rocket > fly. Hello world. > > — I really do not expect more than ‘read and copy and play and feel somewhat > confused.’ That’s why I announce it in the Preface. > > — I also wrap up the Prologue with “You are not a programmer. Let’s get > started.” > > POSSIBLE ACTIONS: > > — I could try to turn the links off in the Prologue. But I want to get > students in the mind set — look at the docs — because programmers must learn > to look at docs. Unless they want to stay Stackoverflow coders. > > — I could try to weave in another warning into the Prologue that this is > meant to be read quickly in the above spirit. > > — Do you have any other proposals? > > > > > > > > > > On Apr 9, 2017, at 2:45 PM, gfb <g...@cs.toronto.edu> wrote: > > > > 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. -- 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.
