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

[Chris McDonough]

> 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.

Sure... coming up with a taxonomy is largely an exercise in reviewing what
exists and iteratively expanding and shrinking the taxonomy to accomodate
most existing material.  Note that there is a sort of nominal taxonomy on
Zope.org that isn't well-exposed that lets folks categorize Products and
Howtos already.  I hope to be able to have the time to tackle the
organization of this after the "official" docs situation is straightened
out.

> One note - why can't I
> find a table of contents for the Zope book on the site?

I'm not sure... what about http://www.zope.org/Members/michel/ZB?

> 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.

Yup.  Unfortunately, this requires building some nontrivial tools.  I'm
afraid to even think of building them until some pronoucement is made about
the state of new.zope.org, because I don't want to duplicate effort or need
to rewrite the tools. :-(

> Of course some kind of standards
> document would need to be written.

Official standards of documentation exist now at
http://www.zope.org/DocProjects/ .

<snip other good comments about developing software like new.zope.org ;-)>

> 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.

Have you seen ZopeLabs at http://www.zopelabs.com/ ?  Adam Kendall does a
nice job of providing a place for cookbook-like recipes here.

- C