[Zope3-dev] Zope 3 Documentation and Quality Assurance

[David Harris]

[Brad Bollenbach]
<snip>
> In any case, IMHO, this can only reflect poorly to potential users of Zope
3.

Everyone knows by now that I'm a newbie. As such, I'm supremely qualified to
comment on how potential users perceive the Zope 3 documentation. I
represent the "short bus" community, where everything is too hard to look up
and standard jargon reads like "the flay rod's gone a-skew on the treadle".
Citing a specific example (an exercise which may prove counter-productive
because the discussion may founder on the merits of my analysis, instead of
Brad's call-to-arms - please, please, regard the following as a humorous
anecdote):

Slide 7 of ProgrammerTutorial is confusing on several levels.

Believe it or not, I got lost right at the top. I tried to make sense of the
title, "Step 1, minimal contact class", drawing on the information imparted
in the previous slides. Amazingly, my brain tied the phrase 'minimal
contact' to the idea that Zope 3 tries to do a better job of isolating
presentation and content. In my mind, I thought the first step involved
classes which had minimal contact with the underlying core. Haw-haw.

I believe I puzzled out the next line correctly, but it took a couple of
readings. "In this step, we present the typical steps necessary to get a
class usable in Zope". First off, this tells me that the first step is not
actually the first - there are other 'typical' steps. Next, the 'slang'
usage of 'get' is very misleading. On first reading, it appears the student
will use these instructions to retrieve 'a class usable in Zope.'

(I am not forcing any of this. I really, really read it this way.)

Still on the same line, I had to wonder: "I'm supposed to be getting a class
usable in Zope. I thought Zope was about content types, components, and
objects. Where does 'class' fit in? Why start there?" Mulling it over, I got
side-tracked by an analogy (probably a false one.) I started thinking that I
was learning how to build a house by drawing a window. Not any particular
kind of window, just a window.

Obviously, my mental state was worsening rapidly at that point. So the next
line on the slide threatened my sanity: "Create a contact package (e.g. In
zopeproducts)" Short and sweet, I says. By now, I figured out (by peeking at
the next slide) that contact was actually a person. And I know enough Python
that 'package' could mean a Python package (but maybe not, better keep an
open mind.) But then it all fell apart when I went looking for zopeproducts.
No such directory. I see zope.products and zope/products and I even see
zopeproducts (one word) referenced in a text file. Now I'm lost - where am I
supposed to be working?

My parsing engine broke down on the next line: "Create a basic content
class, Contact in a contact module." Is there a missing comma, a missing
word, a missing phrase? What is a contact module? Is it a Python module
(script) named contact.py? Why not say so? Since the instruction was not
worded that way, it must mean something else.

And on and on...(my brain hurts!)

When I started this explication, I mentioned confusion on several levels.
One of those levels is typography - there are four different type faces used
in the body of the slide. Only the Courier font can be differentiated at a
glance. The line "Create a basic content class, Contact in a contact
module." has three similar looking fonts.


In all seriousness, the mocking nature of the previous analysis is not
directed at any author, but at myself. I apparently need guidance, and I
believe I am not alone in the world of 'potential users'.

Dave Harris