On Wednesday 06 June 2001 19:43, Chris McDonough wrote:

...

Well some of the things that Owen Taylor says, are - unfortunately - true. Zope isn't well documented.

I wonder how long this meme will continue. We now have the Book, a prototype developer's guide, the help system (with an API guide), 312 howtos, and a cookbook (via ZopeLabs.com).

I think folks need to start becoming more specific when they say "Zope isn't well documented".

- C

Sorry let me correct myself: Zope Products (the Products submitted by Zope users) aren't well documented (the use of them). Regards, Gitte Wange

Hmm, To put in my two cents, I think perhaps there just needs to be more comprehensive in-points to documentation when seeking an answer. I would rather sit with a smoke and coffee in the morning reading some _well written docs by someone who makes a business of it, instead of crawling through lists and _hoping someone answers my usually idiotic question that is better dealt with other ways. When presented with the same site you just downloaded your first zope, I'm left with the impression; 'Um, whats next?'. Had this very email come to me from a gratuitous 'Thanks for downloading our product', much like 'for-sale' software is, I'd have at least 3 places to start looking. I sometimes get the 'ole-boys club' feeling where Unix is lore and since python makes most sense there (not that its less on windows, but come on, who would want to use that for slinging code?), there are more things 'You just have to know' than I am comfortable with. Mostly of what I say is true anyhow, but that can easily be remedied when you pre-empt that people arent going to understand you when you only explain the contraindications of the result instead of purpose and cause, and expected/intended behavoiur. All things aside, I feel Zope is misrepresented in this manner. Problems solved by answers is logical but don't always come immediatley, but the frustrations of not finding the path to the answers is your worst day at work. Its sorta like that proverb 'Teach a man to fish and he'll eat for a day.....'. Give us a good starting point and encourage people to use it. 2 cents from a total non-programmer who rocks zope. Paz -----Original Message----- From: zope-admin@zope.org [mailto:zope-admin@zope.org]On Behalf Of zbir@urbanape.com Sent: Wednesday, June 06, 2001 8:06 PM To: zope@zope.org Subject: Re: Zope docs (was Re: [Zope] I was wondfe)

...

Well some of the things that Owen Taylor says, are - unfortunately - true. Zope isn't well documented.

I wonder how long this meme will continue. We now have the Book, a prototype developer's guide, the help system (with an API guide), 312 howtos, and a cookbook (via ZopeLabs.com).

I think folks need to start becoming more specific when they say "Zope isn't well documented".

I think it's more along the lines of "Zope can't read my mind!" $name="zachery bir"; $email="zbir@urbanape.com"; $position="systems administrator"; $altposition="witch doctor"; $voice="804.353.3742"; $web="http://www.urbanape.com"; _______________________________________________ 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 )

I think folks need to start becoming more specific when they say "Zope isn't well documented".

Chris, The following is a rant :-) Read the recent Digital Creations survey. Lack of documentation is by far the most prominent complaint. That's not random people bitchin', that's statistics :-) Zope Book was no good before it went through editorial process. Developers in DC write excellent software but horrible docs. They need an editor to tell them that documentation is not only about pure definitions, but it actually needs examples (and more examples <and yet more examples>). And it needs repeating things that were already mentioned elsewhere in the book, because people forget. Some people outside DC (or at least myself) are not as bright as DC people. Now that we have CMF, DC is doing the same mistake as if it never learned anything. There are no docs, just random data in the fishbowl. Just look at it from a moron's perspective (a moron like myself) and you won't be able to make any sense of the docs scatterer around fishbowl. CMF is very exciting but I decided to not touch it before there are any good docs. Standardised, revised, edited docs. A year ago I suggested (to Amos, I think) that DC hires a full time technical writer, or a bunch of writers, or contract them. DC replied that they will consider this idea. What happened instead was that the programmers (Michel Pelletier and Amos Latteier) wrote the Zope Book, and it required a long editorial process to make it readable and easily understandable. In my humble opinion you should not let programmers write the documentation. I am a poor programmer. I take very long to write a program. I enjoy writing documentation. But bright, effective programmers do not enjoy it. Forgive this rant. I would not write it if I did not care about DC and Zope. In my opinion, the documentation, be it Zope development, CMF, or Products, is not something DC could be complacent about or satisfied with. Best regards -- Milos Prudek

Since I started this thread, I'd just like to pipe up and give my 2 cents. -Zope does now have some docs. Great! -Zope needs more docs. I'm thinking something along the lines of Java's Documentation. I've written a few (never published) zope products and the only thing I can say is that I'm still not sure why somethings work, but because I saw the code in an example and it did what I wanted I used it. I think the core Zope classes and their methods needs to be put in some sort of document, indexed and possibly with examples. On Saturday 09 June 2001 03:11, Chris McDonough wrote:

Hi Milos,

On Sat, 09 Jun 2001 15:10:11 +0200

Milos Prudek <milos.prudek@worldonline.cz> wrote:

...

...

I think folks need to start becoming more specific when

they say "Zope

...

isn't well documented".

Chris,

The following is a rant :-)

I appreciate the warning, but IMHO we need fewer rants and more energy spent doing creative things. ;-)

Your message called for better CMF docs. That's specific enough for me.

- C

_______________________________________________ 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 )

-- Edward Muller - edwardam@home.com - edwardam@handhelds.org There are two kinds of people, those who do the work and those who take the credit. Try to be in the first group; there is less competiton there.

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 )