[plt-scheme] Teachpack Writing Guideline

On Oct 15, 2007, at 4:39 PM, R. Emre Başar wrote:

> Hi,
>
> I'm trying to create a teachpack for some course material which we use
> locally. Are there any guidelines or a public policy to followwhen
> creating teachpacks? I've tried to find documentation on that topic  
> but
> I was unable to find one.
>
> Does that mean I can create teachpacks the way I like?


Yes and no. In principle, you can use any module you like as a  
teachpack.
But in general that won't work as intended for beginners.

The point of using drscheme is to have students use teaching languages
which differ from their full brethren due to their error reporting. It
happens in terms of the small teaching language, while in 'real'  
languages
it happens wrt to that one.

Example:

  (666 (cons 1 (cons 2 empty))

in the full language produces the error message:

  procedure application: expected procedure, given: 666; ...

Of course we know that 666 is not a number. What do you really mean, a
student should ask.

In the teaching language, you get a different response:

  function call: expected a defined name or a primitive operation
  name after an open parenthesis, but found a number

This is far more specific than 666 is not a number.

;; ---

So, to design a teachpack well, you should enforce all obligations
that students' code must obey (in the spirit of contracts) and
issue appropriate error messages. This is easy for first-order
functions (well doable) and somewhat complex for higher-order
functions because I haven't gotten the contract system to say
the right things. [Robby and I need to figure this out still.]

I recommend looking at the provide specs and the error checking
in world.ss and copying this set-up.

;; ---

I guess it's time to write a doc.txt.

-- Matthias