[Zope] Use the source Luke -- what could be done to help documentation process? Request

[A M Thomas]

Hello all,

I'm also a newbie at Zope, but I've been interested in process
management and workflow stuff for a while - although I'm not nominally
working in those areas.  Forgive me for my newness and ignorance, but I
do like Zope a lot (I just set up an iMeme account this weekend) and I
would very much like to see the documentation get better.  For all I
know, most of the suggestions below are already in the works, but I send
them anyway in case they might be helpful.

My main ideas, which I humbly submit for debate, rejection, or
expansion, are:

1) Before going much further, you might want to document a good taxonomy
for breaking down Zope topics.  I have the Zope Book, and the table of
contents is a good start, but I bet the community could break it down
better and flesh it out more. 

I think I'm still too new to propose a good breakdown myself (although
my content management product is coming along fairly well), but as I
said, the table of contents of the Zope book is a good place to start. 
As a newbie, I'd have loved to go to the documentation page (or a page
one level below it), and seen a map of topics.  One note - why can't I
find a table of contents for the Zope book on the site?

Obviously the howto's would be organized under this scheme, and it's
unavoidable that such a scheme would be created.  But I'm suggesting
that the taxonomy be created first, with the goal of organizing the
information that should eventually all be present in a way that will
make sense to a relative newbie, rather than organizing existing
documents into groups and proceeding from that standpoint.

2) Volunteers could be matched with the particular area of the taxonomy
that interested them, and they could be in charge of that section of the
documentation.  My further thoughts here are influenced by the Open
Directory Project (dmoz.org).  When new documentation content is
created, the creator could suggest the area (or areas) that should house
that content; it could even appear immediately in that area, but the
doc. editor for that area would review it, make sure it fit, possibly
suggest that it go into another area (instead or in addition).  With
existing documentation or how-to's, these volunteers could be in charge
of finding any documentation that fit their area and adding it.  This
could break a huge job into 10 or more pieces instead of having it all
fall onto three or four people.  Of course some kind of standards
document would need to be written.

2) Probably a particular piece of documentation (how-to) should be
allowed to be in more than one part of the taxonomy, but perhaps should
have just one "primary" area in the taxonomy.  This is so that doggedly
systematic people who want to know *everything* can just read all the
documentation from start to finish without worrying about duplicating
their efforts - a view of the information could just put everything
under its primary area, with links to sections for which an area is
"secondary"

3) Each piece of documentation, or how-to, should have the following
information: date created, date last edited, versions of Zope for which
it is known to be correct, versions for which it is known to be
incorrect, author, primary topic, other topics (I just started using the
word topic for taxonomy sections, or "areas" - I think topic works
best).  The Zope version information is important, I think - I keep
running into stuff that I'm not sure is still correct or relevant.

4) I'm a Perl programmer - not a super great one, but quite adequate.  I
know you guys have looked at CPAN and there's talk about organizing
products, and I've touched that before.  I will say that in addition to
a rating and review system (like tucows or the CGI resource index has),
I wonder if a Zope-version-for-which-it's-known-to-work field would be
useful here, too.

But my main reason in bringing up Perl is to mention my second most
valuable reference book: The Perl Cookbook.  Oh, it's great.  It would
be so wonderful to have a well-organized collection of short Zope
"recipes" to draw from.  Short is important - each recipe shows one main
aspect of the language or one technique, and strips away unnecessary
code, so a reader can grasp very quickly the essential thing they need
to know.  This is significantly different from a complete example
product or application.  The intended audience is not really a complete
newbie anymore - it's someone with a basic grasp of the technology, but
who doesn't know that "aq_parent" is the thing they want, or how to sort
things in a <dtml-in> list, or how to render text as structured text.

They're not even sure what to call what they want to do, so again, a
good organizational scheme (taxonomy is my word of the month, I guess)
is crucial, because if you can't find the information, it might as well
not be there.  But so many questions and problems I've run into, I knew
others had run into before me - like the questions I'll probably ask
about folder organization or updating properties.

Yes, the mailing list archives have a lot of great stuff in them, but
it's hard to find in there - again, if a volunteer were assigned to each
topic in the "cookbook" (better word for cookbook, anyone?), that person
could watch the mailing list for pertinent postings, maybe massage them
appropriately before adding them to the cookbook, or ask the author to
submit the tidbit to the cookbook in some agreed format with some set of
agreed-upon assumptions.

-- About searching:  Searching is great, but it is not a perfect
solution.  How do I know that my problem with object references will be
under "self"?  If I search for "parent", how many hits will I get, and
how do I know if my problem has anything to do with that word - I'm a
newbie.  With a good hierarchical organization, I can be sure I've
looked in all the right places.  I don't mean to be critical - what I've
found has been great - but I have found overreliance on search as a
means of "getting to" information to be somewhat frustrating.  "Tables
of contents" are still very relevant.

OK, thanks for listening.  Feel free to tell me how wrong I am...

- Am