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

From: Matthias Felleisen (matthias at ccs.neu.edu)
Date: Fri Jun 3 16:17:25 EDT 2011

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. 


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/

Let me know when it's settled. I'd be happy to edit the
draft documents and I'll tackle the teachpack error messages

-- 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

Posted on the dev mailing list.