Douwe wrote:
I think there are two issues here at stake. One, the Zope documentation, which is actually quite ok. There's the book, there are a number of howto's and there is the source code, which is really readable.
I understand what you mean, but... Why is it then that it regularly occurs that I see a question on the mailinglist that gets an answer like: "You shouldn't use product A, but B..."? Followed by: "Because" "it's no good..." or "it's not maintained any more..." or "with B you can also..." or "in B you don't have to...".
The second issue is the nature of Zope. Guido van Rossums dictum that there should be one perfect way to do something, doesn't fly for Zope and in that way Zope is more like Perl then Python. For one problem, there are lots of solutions, different products, different approaches, different programming languages (DTML, Page Templates, Python). There is no one true way. Some people write complete applications in DTML, others package everything in products written in Python. Yes, very confusing at first sight.
If there is no one true way, there is no one true set of documentation.
Of course I do agree that better documentation is always better.
Maybe we shouldn't talk about a true way, but about a *preferred* way. I really think it's a damn pity to learn something, try it, have problems and finally find out I'd better done it in another way. That's not very encouraging. Don't you agree? Best regards, Yvon Breuer
-----Original Message----- From: zope-admin@zope.org [mailto:zope-admin@zope.org]On Behalf Of Breuer, Yvon Sent: Friday, August 09, 2002 11:01 AM To: zope@zope.org Cc: zope@toenjes.com; jprice22@wvu.edu Subject: [Zope] Zope Documentation
Hi *,
I *really* think it's time to make a strong effort to get a better Zope documentation. According to me many people agree that something needs to be done. But I also think that it's not very clear *how* it should be done the best way...
Trevor Toenjes has made a very good 'beginning'! (Although beginning probably isn't the best term for it.) Maybe it's sufficient to extend his work with some ideas from Patrick Price. I'd like to ask you *all* to (re)think about *what* needs to be documented and *how*.
We need two types of users for this discussion: 1. experienced users: Together (!) they know what's good about Zope, they know the best (or 'preferred' products, they know what should be the best way to *learn* and how to *use* Zope, they know which questions are asked many time, etc. etc. 2. unexperienced users: Together (!) they know what is missing, what is unclear, they still have a fresh look at Zope and probably wonder why something is done 'this way' and not 'the other way'.
Don't forget that the early users have grown into Zope and it's continuing expansion (as in users, as in complexity, as in possibilities, as in ...). It looks like newcomers can't see the forest anymore because of all those trees standing in the way... (It's a freely translated Dutch saying.)
Last example (see other examples below!!!): I'm working myself through the ZopeBook at the moment. It's *really* helpfull and I learn constantly, but: At first I read about DTML, about how good it is and it's possibilities. Eveything ok. After that I started to read about Page Templates. Again even more (and nice) possibilities, but it also said somewhere that it's better to use Page Templates instead of DTML... So, why learn DTML first? A bit further it's even said that it is even better to do everything with Python... So, why not forget all about Page Tamplates and continue with Python? Isn't that strange? Isn't it confusing? When do use what? And Why? Which products exist? What do they do? How do you know? Is it a good product (according to the community)? Is there a newer/better product?
Please, take it up!
Best regards,
Yvon Breuer
Patrick Price wrote:
Idea mode on:
Is there any kind of Zope Tutorial Tool out there? Something for throwing together instructional pages like the Zope Tutorial? Something that could be used for ANY kind of tutorial, slide show, web-based learning, etc.
At the very least a more comprehensive tutorial than focusing on Elvis sightings (which is a good tutorial, don't get me wrong)
And before you tell me to write one myself, I have to learn Zope and Python first... By then I'll have some good ideas of what to put in a tutorial, but by that time I'll know Zope and everything that's now unclear will become clear, and I'll think "Why bother? That's *basic* stuff."
Rant: While I'm on the subject of documentation, it would be nice if every doc standardized on having sections like:
What do I do with this? Practical example for the uninitiated. Like, "if you don't understand authentication, look at *this* link." before you even try to use this product. In other words, not only show the *software* dependencies, but show the *knowledge* dependencies. Think how fewer emails you'd get from people like me asking silly questions.
What does it look like? Screenshot? (Save me the bother of installing yet another calendar package, trying to figure out how to use it, then seeing that the output is *crap*, and uninstalling and having had to restart the server *twice*.) I *love* product pages that have screenshots or show an image of what the control will look like.
and
When you have a nice web page with cool widgets/whatnots, tell people how it was implemented in size-2 type or something. Are you afraid I'll steal your design? Hey, that's how I learn! The ZDP comes to mind. How do they do that? Is it mentioned on that page? Nope. No, "this wiki based on wackproductZ and CMF". I see so many nice web layouts and have *no* idea how they were done, what products were used, nada. It's a shame.
People learn stuff then take it for granted.
Ah, the curse of learning. Thanks for letting me spam. Filter on.
-Patrick Price
Trevor Toenjes wrote:
There has been a community project afoot that stalled a few months ago to address much of your concern with documenting products. It stalled because developing a production process that fits everyone's current development skill level, favorite tools, and time commitments is challenging. The NZO (new.zope.org) project is meant to be THE community project to alleviate ZC's sole duties of maintaining the community's website.
Below is a link to the new Products screen that is only waiting for final development and then deployment. http://www.zope.org/Members/trevor/productspage/
We need HELP! to finish this project. Migrating the old "software product" data to the new schema requires much more time than just conceiving a GUI.
Now that you know that ZC is trying to get the community to control all documentation on zope.org, please join the zope-web@zope.org mailing list and lend a hand. PLEASE, pretty please. We, as a community, just need to pick up the ball and finish the game.
Yvon had a couple new subtle points that I will add to the "vision" of the new products section.
Cheers, Trevor
Jack, Charlie, and Yvon supposedly said:
Jack Coates wrote:
So, speaking as a perennial Zope newbie, I have to say that I'm getting nervous about seeing all the things that I use fall one-by-one into the "that's depreciated, use this other cool product instead." I don't think I have a right to complain, but I'm complaining any way :-)
Charlie Reiman wrote:
Technically, no, you don't have a right to complain but you do have a very good point. I'd like to echo it and point out the problem is exacerbated by zope.org not having a strong way of marking docs and products as deprecated. I hate finding a cool product, downloading and installing, only to learn it fell out of fashion with 2.something. Ideally, such pages should be marked and linked to whatever is the latest greatest substitute or just marked as dead to Zopes 2.x+
Yvon Breuer wrote:
I totally agree!
Maybe it's an idea to create a list (or database, or spreadsheet)on Zope.org that shows the 'preferred product' per task. Since I'm quite new to Zope it's better that someone more experienced creates it AND keeps it up to date (otherwise it wouldn't be usefull :-)
Something like this I think would be helpfull: - task - short task description - preferred product - short preferred product description - since when it's a preferred product - since which Zope-version it's a preferred product - link to extensive product description
Hopefuly somebody has a crack at it. ;-)
Yvon Breuer
_______________________________________________ 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 understand what you mean, but... Why is it then that it regularly occurs that I see a question on the mailinglist that gets an answer like: "You shouldn't use product A, but B..."? Followed by: "Because" "it's no good..." or "it's not maintained any more..." or "with B you can also..." or "in B you don't have to...". [...] Maybe we shouldn't talk about a true way, but about a *preferred* way. I really think it's a damn pity to learn something, try it, have problems and finally find out I'd better done it in another way.
That's not very encouraging. Don't you agree? Of course I agree, it would be nice if things were more clear. But the question is preferred by whom? I use LocalFS, even though it is no longer maintained it seems and I'm sure there are a number of products B better in one way or the other, but I happen to like LocalFS, so there you go. Same goes for DTML vs Python. I actually think the ZopeBook does a pretty good job. If you understand everything in the book, you're pretty much there.
On the other hand, I think you have point when it comes to products. As far as I know, there is not really a general product guide. Douwe
Breuer, Yvon writes:
... Maybe we shouldn't talk about a true way, but about a *preferred* way. But your preferences are not necessary mine and mine even vary with context...
Let's try an example. What's better, a Folder, a BTreeFolder, an OrderedFolder or an OFolder (you do not know this one, its the unpublished tiny cousin of OrderedFolder)? Answer, it depends. When my folder contains up to (say) 50 elements, a Folder is better than a BTreeFolder. When the folder contains many thousand elements, a BTreeFolder (or even the new, not yet officially released BTreeFolder2) is better. When I need to control the element order, I need "OFolder" or "OrderedFolder". "OFolder" just allows to control the element order, nothing more. "OrderedFolder" has lots of additional features: optional transparency, optional localization. But it depends on several additional products and it refused to get installed when I tried for the first time. Another example. What database is better: MySQL, PostGres, Interbase/Firebird, Oracle, .... It depends... What is prefered depend on the persons, the contexts, the circumstances. That the Python world is simpler depends on the Benevolent Dictator. That the Zope world is much richer is caused by the lack of a dictator. Many people develop Zope products and donate them to the community. Almost all of them are useful in some context. Who should become the dictator that says, this product must not be on the Zope portal? I am very happy with the community's democratic nature. I would not like a dictator that decides on whether a product can or can not be on the products list. But I would welcome an annotation service, where users of a product can comment in such a way that other users learn about their experiences (something like the reader reviews on Amazon.com). And maybe, a preference rank for products in a group may help (something like the purchase rank on Amanzon.com) automatically determined from the number of downloads or derived from some explicit rating.
I really think it's a damn pity to learn something, try it, have problems and finally find out I'd better done it in another way. Isn't this quite normal with learning?
When I finish a project, I *always* know lots of things I could have done better...
That's not very encouraging. Don't you agree? No. I like learning. And learning means that I can make something better after than I could before...
Dieter PS: you could learn to strip your quotings down a bit.
participants (3)
-
Breuer, Yvon -
Dieter Maurer -
douwe＠oberon.nl