[ZDP] Documentation Plans

Rik Hoekstra hoekstra@fswrul.fsw.leidenuniv.nl
Fri, 20 Aug 1999 10:34:58 +0200


<snip much of a good post about rearranging the documents>

> We have some ideas about implementation...  However, before we go there,
> I'd like some (any) feedback on what I've said here...  PLEASE, PLEASE,
> PLEASE -- let's try and keep the discussion of documentation on the ZDP
> list as opposed to the main Zope list.  It gets hard to ensure that
> things don't fall through the cracks if valuable comments and ideas are
> posted to multiple venues.
>

I think your reorganization plans are sound. A few questions and
suggestions:

- Are there any plans to integrate all this with the efforts of the ZDP. In
other words, what parts of the documentation does DC think the ZDP should
cover, and which parts we should not worry about?
- If a may make a suggestion about the usability of the Howto's: please make
them usable separately _and_ in sequence (perhaps together with a
users/readers guide). This may be done by including 2 different examples:
* the first as a stand alone example, explaining the ins and outs of the
subject of the Howto by itself, and
* the second by explaining it in a larger context enhancing the examples
from earlier Howto's and making the added value visible. By this I mean that
if you follow the Howto's, at the end you will have a working site, with all
features of Zope exposed together in a coherent way.
Perhaps the sequential examples could even be distributed as a sample site?

This will require a bit more work, but increase the usability of the code a
lot!


Just my $0.02

Rik Hoekstra