[Zope] Zope Documentation in general

[Patrick Price]

Here's my general take on spending about a week looking for good Zope 
documention  (from a newbie perspective)...Pardon me if this is too obvious.

I'm finding that Zope documentation  has these common problems:

I finally found the How-To's by a roundabout route - I would search 
Google for "Zope" and my subject, then I'd find these wonderful 
How-To's, but, they all seemed to be owned by separate authors and there 
were no links from each How-To back to a master table of contents, nor 
an index.   Each page was by itself and had no hooks to any other 
documentation.  It seemed in every case I was at the end of the 
documentation line.  I didn't know where the "master list" of these 
things were.    Eventually I came to find the Docs link on the Zope.org 
site. 

Then I found that the "basic" how-to's which applied to me are sometimes 
old and thus hard to find (initially).  I found that by going to Docs, 
All How-To's, then setting the Batch Size box to the total # of entries, 
I could scroll to the bottom of the entire list and start finding the 
stuff I wanted  to read, like:

Gotchas for Zope Beginners 2000/10/16 jens
 Zope Installation Choices 2000/08/24 guy_davis
 Z Catalog Tutorial 2000/10/16 Amos
The DTML Name Space How-To 2000/10/16 michel
Getting Started With DTML Scripting 2000/10/16 Pam

You get the idea... notice the dates on these.  Unfortunately for this 
layout, the how-to's get more complex as time passes.  So as a  new Zope 
user, I initially see a bunch of high-level stuff at the top which 
usually isn't basic information.  Almost enough to make me give up 
because I spend all my time searching for documentation relevant to my 
skill level.   I have to dig  to find the "good newbie stuff" at the 
bottom.  This makes sense in terms of "starting at the bottom" for new 
people, and allows people more versed in the product to "find the 
latest" at the top, however the ordering as it is, is "static", 
appealing to one mindset.  It is limiting.  Perhaps rating systems and 
voting on the most popular/helpful documents is the answer?

The other thing I'd like to mention is that I haven't yet found an INDEX 
for this stuff - like the kind you'd find in a good book.  Are there no 
keywords for these documents?  Must I forever be performing text or 
Google searches on everything?   I come across the good docs *almost 
always* as a result of someone  making a URL mention in an email.   It's 
almost a shame that subscribing to a mailing list is the best way to 
find where the documentation is.  Lists are a good thing, don't get me 
wrong, but still...not everyone knows the value of mailing lists, or has 
the time to scan everything.
 
  I'd like to see some sort of knowledge-base product for Zope 
documentation, something that would open up the Zope world to me by 
asking  "What level are you?  Beginner?  Well then, here's what you need 
to be looking at to make you smarter."   "This How-To rated Beginner." 
or  "Warning: complex subject ahead."

With "rating systems" then I could do the driving, rather than me having 
to adapt to how someone else decided the documents should be presented. 
 Maybe then I could avoid wading through the latest greatest information 
which is often tantalizing but ultimately confusing for my beginner 
status.  

I'm not after slamming Zope.org or the documentation itself.   I have 
the same problems finding stuff every time I undertake document 
research.  I just have this feeling that Zope can do all this and more. 
 Is it already being done?

I propose that a few documentation implementation standards would go a 
long way to helping the community at large:

1: indexes of document collections
2: keywords for searching (same as index, really)
3: tagging the document with the level of the target audience knowledge 
level (beginner, intermediate, advanced)
4: listing the Zope version/date which was current at the time of the 
document's creation
5: screenshots of the product or diagrams (yeah, I ask a lot)

Thanks for the forum.  I plan to buy some books soon and climb out of 
this primordial Zope/Python soup so I can stand among you. :-)

-Patrick Price
 West Virginia University

PS: Another  problem (presentation-wise and not functional-wise, and 
easily corrected) with the Zope.org how-to's is the alternating 
grey/white layout.  While viewing the list of HowTo's, one howto is grey 
background, the next white, the next grey.  While visually pleasing, 
this format doesn't make the  Subject stand out.   One Subject is grey, 
the next white, etc.   I think the subjects should have their own 
background color.