[ZWeb] Zope.org feedback: Welcome to Zope.org

Ken Seehof (via www.zope.org) kseehof@neuralintegrator.com
Wed, 11 Dec 2002 02:32:02 -0500

This needs to be forwarded to everyon who writes Zope documentation:

You need to be much more aware of your audience.  In general, people who read documentation do not have as much contextual knowledge as the authors.  This seemingly obvious point is consistently missed by Zope technical writers.  It's really a shame because once I understand the basics, I find Zope very easy to use.  Unfortunately, consistently poor documentation has created the impression that Zope is difficult to use.

Here's a typical example from the online help, in the chapter "API Documentation - ObjectManager":

... self.manage_addProduct['OFSP'].manage_addFolder(id, title)

What the heck is 'OSFP'?  I can't find a reference to it anywhere!   The author obviously assumed that the reader (who presumably is just now learning about the ObjectManager class) already knows all about 'OSFP'.  Why would he know that?

I could go on with dozens of examples, but I think you get the picture.

Every time you write a paragraph of documentation, ask yourself: "Can I reasonably assume that my audience (people who are in the process of learning the material that I am writing about) have sufficient contextual knowledge to benefit from reading this?"

- Ken Seehof <kseehof@neuralintegrator.com>

This email was generated from the Zope.org feedback form
It was invoked from a link on http://www.zope.org