[ZDP] REVIEW: Proposed Zope Developer's Guide Outline

[Amos Latteier]

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:

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

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

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

Please note that these are just my personal opinions. I agree that we
should try to avoid overlap in our documentation efforts. However, I am
very grateful for the ZDP's efforts, and I don't want to be telling you
what to do.

I can see that it would be useful for the ZPD to have a better idea of what
DC is up to on the documentation front, so I'll try to put together a DC
Documentation Roadmap soon and post it here for review. If you have
suggestions for what DC should be focusing on, please let me know now;
don't wait for me to post the roadmap.

Thanks.

-Amos