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

[Chris McDonough]

Thanks for the note Ken.

Documentation for Zope is currently a volunteer effort, so it's not
surprising that it's not as polished or as comprehensive as many would
like it to be.  I am one of those volunteers and I am painfully aware of
the holes and inconsistencies in the current documentation set.

That said, the most sure way for it to improve is via comments to the
online books.  If you've not already done so, I would add this as a
comment to the API Documentation chapter of the online version of the
Zope Book.

Thanks,

- C

On Wed, 2002-12-11 at 02:32, Ken Seehof (via www.zope.org) wrote:
> 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
> 
> 
> _______________________________________________
> Zope-web maillist  -  Zope-web@zope.org
> http://lists.zope.org/mailman/listinfo/zope-web