[Zope-dev] Speed up the learning curve

[Rene Pijlman]

[Clear error message when method in Python-based product has no
doc string]
> Doesn't it do precisely this when you run Zope in debug mode?

I don't know, you may be right. I'll look into that. Thanks.

But still, catching errors is not the same as debugging. I think
Zope will be user friendlier when it gives a better error
message directly.

Coincidentally, I just received this Alertbox:
"Established wisdom holds that good error messages are polite,
precise, and constructive. The Web brings a few new guidelines:
Make error messages clearly visible, reduce the work required to
fix the problem, and educate users along the way."
http://www.useit.com/alertbox/20010624.html

This is good reading for zope-dev's :-)

It contains an interesting idea with respect to the learning
curve:

"Users read system documentation only when they are in trouble
(that's the Second Law). They are particularly attentive when
they want to recover from an error. Given this, you can use
error messages as an educational resource to impart a small
amount of knowledge to users. Of course, error messages should
be brief and to the point, as should all Web content. However,
error messages can still teach users a bit about how the system
works and give them information they need to use it better. To
further that end, the Web's underlying technology makes another
guideline possible:

Hypertext links can be used to connect a concise error message
to a page with additional background material or an explanation
of the problem. (Don't overdo this, though.) "

He's right. It really would have helped if the Zope error
message linked to a page explaining the error message, listing
possible causes and advising to run Zope in debug mode.

Would it be possible to link Zope error messages to a website
(with a unique page for every error)? Maintaining the
documentation per error on this website could very well be a
community effort of course.

Regards,
Rene Pijlman