Thanks for this document. For my own teachpacks, I tried to make the error messages consistent by creating all error messages in one file (htdp/error). But you're also reducing their complexity and this is even more important. The key is that students must understand the problem.
A couple of comments: 1. We need to create a glossary for all terms used in error message and link them to the teaching languages. 2. You rule out some words that are consistently used in HtDP. I don't doubt that you have a rationale based on studies of students and I not interested in bringing these words back. But teachers may use them, and students may read them. "Constructor" and "selector" and "predicate" come to mind. So: 1a. We may wish to supplement the entries with synonyms that connect the words to equivalent words in HtDP. 3. The guidelines should go into the docs as a scribble document. We should supplement them with a document on how to write teachpack. For now, this document could just point forward to your document. They should also be linked to from a file in the lang/ documentation. Let me know when it's settled. I'd be happy to edit the draft documents and I'll tackle the teachpack error messages then. -- Matthias On Jun 3, 2011, at 1:21 PM, Shriram Krishnamurthi wrote: > Guillaume, Kathi and I have created a set of guidelines for writing > error messages for *SL. For consistency, these guidelines need to be > used also by authors of libraries including Teachpacks, etc. These > guidelines are currently being applied to all the error messages in > *SL in the core distribution. > > Please review these guidelines and let us know if anything is > unclear. We'd like to hear back from you within a week, by > > Fri, June 10 > > We have had to compromise on the description a little to make > everything fit into a small number of pages, which we did because we > really do hope people will print these out and put them on the wall or > next to their monitor to refer to while writing code. Therefore, > lengthy descriptions are out. > > In particular, rationale is also out. If you are curious about the > rationales for any of these things, please do ask. > > After this is settled next week, we will send this to users@ and also > to edu@ to tell instructors to follow these terms. > > Thanks, > Shriram > <error message composition > guidelines.pdf>_________________________________________________ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev _________________________________________________ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
