Thanks Alex, that was very helpful.

> it is not clear from the document how any of it can be useful.  

I got this same feedback from some friends on the 0.1 release.

Also, it is not clear
> what `Department?` and `Course?` are in the first code snippet -- are they
> functions that the user has to provide or is it something that your library
> generates by looking at the database schema?

I was planning on building the "generate functions by looking at the 
database schema" functionality later, but now I realize it might be a 
prerequisite for good documentation.

I would suggest to provide a database schema and some sample data in a
> database, and use this in the subsequent examples.  Start with a simple but
> complete working example and construct more complex, but still complete and
> working examples from them, at each step illustrating the benefits that the
> library provides.  Maybe contrast each step with how the plain SQL would 
> look
> as well?

I'm glad you said this because I am planning on doing this. I wrote the 
post you read hoping I could revise those ideas into a shorter, punchier 
"opening argument" before starting the slower walkthrough. But if it wasn't 
clear to you, I don't think I can possibly make it clear to Plisqin's 
target audience (some SQL experience, no Racket experience).

Documentation is hard!

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 view this discussion on the web visit
For more options, visit

Reply via email to