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 )