Zope docs (was Re: [Zope] I was wondfe)

[jacob walcik]

the documentation problem goes way beyond the zope api not being well
documented.  even if someone else has already written products that do
everything i'm wanting zope do do for me (content management, shopping
cart, discussion boards, and web-based email), if the documentation for
the individual products is poor, the product is worthless for anyone who's
not lucky enough to figure out how to use it.  

as far as traditional vs. non-traditional, i'd prefer a well written
readme to having to search mailing list archives any day.  all the content
in one place, no worries about not being able to find certain pieces of a
thread in your search results, etc.  

the how-to's on zope.org are nice, but incomplete.  they either completely
miss crucial steps or they don't do a good enough job of explaining what's
going on to make what they're describing work with even the slightest of
variations.  

i will however say that i agree with the point of the zope function
library being quite well documented.  and i've also been happy with the
dtml docs.  however those are two very tiny pieces of the puzzle.  while
zope itself is very reliable, fast, and full of all sorts of wonderful
features, it remains clumsy to those of us who aren't python experts and
who rely on software documentation when things aren't working as expected.

--
jacob walcik
jwalcik@notwithstanding.org

On Sun, 10 Jun 2001, Philippe Jadin wrote:

> > > > I think folks need to start becoming more specific when
> > > they say "Zope
> > > > isn't well documented".
> 
> Let me add my own piece...
> 
> imho zope is quite well documented. I mean, if you need to find a function
> name and it's use, you'll allways find it in a few minutes. If you need a
> dtml reference, you'll find it. If you need to learn python, well, buy a
> book / see the online site.
> Even the zope api is not poorly documented. (just tried docfinder of
> Dieter - it's a great tool)
> 
> The feeling of people when they say zope is not well documented is probably
> not because there is lack of "traditional" documentation.
> 
> What is really needed is implementations examples of canonical problems.
> 
> imho the most usefull parts of the zope book is the simple guestbook, the
> file librairy, etc...
> 
> The same will go for the next chapters of dieter's book (current
> implementation of a complex website)
> 
> All we (newbies) need is opensourced implementations of sites (an automated
> faq, an e-commerce site, a news page, a thumbnail gallery, a guestbook, a
> forum, etc...) I know those exists as products, but when you are able to
> write products, you don't need this intermediate level of knowledge. and if
> the product doesn't suit your needs, it's hard to customize it.
> 
> The "see source" feature of some zope sites is a great start. It could be
> even better if they allowed you to donwload their sources... (maybe some
> allow this?)
> 
> In one word : no real work needed from DC (beside some finer classification
> of things), most intermediate docs could come from sources of existing
> implementations. Experienced zope webmasters, I (an probably some other
> newbie) need your knowledge!
> 
> And I know this is the role of how to's. They are a great source of help by
> the way. 
> 
> All is fine then ? Almost ;-)
> 
> My 0.02
> 
> Philippe
> 
> 
> 
> 
> _______________________________________________
> Zope maillist  -  Zope@zope.org
> http://lists.zope.org/mailman/listinfo/zope
> **   No cross posts or HTML encoding!  **
> (Related lists - 
>  http://lists.zope.org/mailman/listinfo/zope-announce
>  http://lists.zope.org/mailman/listinfo/zope-dev )
>