[racket-dev] guidelines on error messages -- please send feedback

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