[ZDP] (Fwd) Re: [ZDP] REVIEW: Proposed Zope Developer's Guide Outlin

Rik Hoekstra hoekstra@fsw.leidenuniv.nl
Thu, 20 May 1999 22:20:26 +0001


> Date:          Thu, 20 May 1999 10:37:53 -0700
> To:            Jimmie Houchin <jhouchin@texoma.net>
> From:          Amos Latteier <amos@aracnet.com>
> Subject:       Re: [ZDP] REVIEW: Proposed Zope Developer's Guide Outline
> Cc:            zdp@zope.org

> At 10:38 AM 5/20/99 -0500, Jimmie Houchin wrote:
> >At 04:40 PM 5/20/99 +0200, Martijn Faassen wrote:
> >>Amos Latteier wrote:
> >[snip]
> >>The question now is how we can avoid duplicating efforts. We don't, for
> >>instance, want to spend time categorizing Zope topics if you are doing
> >>it too. We need to figure out (which is partially why you asked in the
> >>first place) how to best coordinate our efforts. Some issues:
> >>
> >>* we're volunteers, don't have deadlines, don't get paid, are lazy and
> >>prefer not doing a thing. So we don't particularly guarantee any
> >>documentation.
> >>
> >>* We are here so we're inclined to do something, though. We must be
> >>nice. :)
> >>
> >>* We won't do it however if other people are doing it anyway. :)
> >>
> >>This isn't an ultimatum or something, just an observation. This is why
> >>Amos needs to figure out what he'll not do and what we should do (and
> >>vice versa we should help him figure it out). Do any of the
> >>doc-categorizer-librarian types have suggestions? They are more informed
> >>on the details than I am.
> >
> >I'll agree with this to a large extent.
> >
> >I would like to see the ZDP pull up alongside of DC and fill in the gaps.
> >If we could have some idea what documentation for them is lowest on their
> >priorities then we can know what best could be our priorities. They can
> >take the priority list and work top down and we can work bottom up. This
> >way when we meet the documentation is complete and little duplicate effort
> >has been made.
> 
> Jimmie and Martijn raise some important points. Let me first say that I
> don't have official DC answers on these questions yet. I am not able to
> tell you the official DC Documentation Plan and Roadmap. 
> 
> Speaking *unofficially*, however, these are my feelings on these matters.
> 
> As far as what to avoid, I suggest that the ZPD not spend too much time
> re-writing material that is already well covered in the existing Zope
> Guides. IMHO the Guides should be the first documentation stop for Zope
> users. If there are problems with the Guides, either changes/additions to
> the Guides should be proposed, or supplementary material should be
> developed. DC should keep the existing Guides up to date and accurate.
> 
> I think that there is a lot of room outside the existing Guides for
> important work to be done, for example:

Duplicating efforts should be avoided if only for the reason that 
even if there is a lot of material available, we need even more. That 
said, perhaps we should think about different levels of explaining: 
from beginner to expert; there should be something there for 
everyone.


> 
>   * The FAQ
>   * The development of the CoolFAQ tool
>   * Collections of examples and how-to style docs
>   * Support/trouble-shooting docs
>   * Zope administration docs
>   * Tutorials that supplement the Guides
>   * Zen-style docs
>   * Cataloging existing docs
>   * Developing conventions/systems for doc authoring and presentation
>   * Full length books
>   * Magazine articles
>   * Quick reference charts
>   * Improvements to the on-line help system
> 
> I believe that right now the existing Guides offer a reasonable, practical
> introduction to Zope. However, as I see it, there are some major gaps:
> 
>   * Examples, especially, DTML examples. You can do some amazing stuff with
> DTML, I'd like to see a DTML cookbook or repository of hundreds of DTML
> snippets that do simple useful things.
>

Agreed!
I think the ZDP should provide example DTML, which are also viewable 
at the spot. In this way people could go to the site with a vague 
idea like I want to make a tree, but I do not quite know whether 
that's possible, and if it's possible, how do I accomplish it. They 
see the examples on the side and think: this is exactly (or 
approximately) what I want.  Or I want something from this and 
something from that. Needless to say the examples should have more 
than one way to access them (from the FAQ, from regular tutorials, 
from the reference etc). This means however, that ideally the 
examples should explore all features of the feature they describe.

>   * Admin, support, troubleshooting. We need a much better repository of
> troubleshooting information to help people install, maintain, and upgrade
> Zope. This information is either scattered or not yet written.

Someone should monitor the list and the Collector for trouble, advice 
and solutions and in one way or another integrate them into the ZDP.

> 
>   * Developer docs. Right now you have to be pretty resourceful to figure
> out how to write products and understand Zope works internally. I am
> proposing a Zope Developer's Guide to address this large issue.

Um, I think the main burden will be upon the DC people, as they know 
how everything is meant to work, in which direction developments 
will be.

[roadmap stuff snipped] 

As we remarked before, there are so many tasks in the ZDP and as 
every effort is voluntary, it is very difficult beforehand whether 
what you do will be duplicate efforts. Perhaps we should 'appoint' 
primary 'editors', or 'coordinators' or even 'owners' for different 
parts of the ZDP? After all, some 'roles' are already unofficially 
getting clear: 
Martijn Faassen is the one who manages the list; 
Martijn Pieters is the technical ZDP guy implementing the CoolFAQ; 
Tom Deprez is doing the ZBook stuff
and there are a few librarians  (I am one of them) who do  document 
mapping (though I am not completely sure what this means...).

Contributions would then still be welcomed from everyone, but the 
editors/coordinators/owners (please do not take this too serious 
though) would be the ones to worry nothing gets forgotton in their 
own area

This is not meant to be formalistic, what do you think. Is it asking 
too much? Are we getting too far away from our comfortable anarchism?

Rik