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
Hi, 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. 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. Douwe
-----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 )
On Fri, Aug 09, 2002 at 11:01:10AM +0200, Breuer, Yvon wrote:
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?
No, a bit, when it works well, because it works well, resp. The DTML/ZPT divide is the most controversial. But it has much to do with history. In the days of yore, you could extend zope by external methods, python products, and z-classes. That was it. (Script (python) is relatively recent.) DTML is very much an exercise in what a "little language" for page design would look like to someone who had a lot of experience in classical imperative programming languages. Behold: alteration, iteration, assignment, all in forms that would look pretty typical to any programmer, if only the <dtml- prefix were dropped. Experience has shown that it was something of a trap. There was a tendency to push too much into DTML, mixing logic (which after all, is what alternation is all about), and presentation. This was, in the mind of its designer, leading to a really awful situation, where logic and presentation were being too intermixed, to the detriment of both. The presentation could not be read because of the logic, and the logic was really slow because it was being interpreted, by another interpreter. ZPT is another exercise in a "little language", based on XML rather than imperative programming languages. I must admit that I did not understand it for far too long a time, and still have not given it all the attention it deserves. But, as I have used it more, I want to use DTML less. Does that mean DTML is obsolete? No, not really, there are times when it is easier to mix a bit of logic in than to create another method. And some things are, in fact, easier to think of in terms of imperative programming languages than in terms of textual substitutions. Well, as to python, it is getting out of the "little language" paradigm (although compared to PL/1, or C++, it is still very much a small language). The ability to easily escape to python is one the Zope's greatest strengths. The pleasure of not having to deal with databases in python is also a great strength! Python has one of the best string handling libraries known, but it is not a templating system.
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
I have been using zope, as a developer, for quite a while now. You newbies have no idea how much easier it is! Back in my day, you had to walk through six feet of snow, against a raging wind, uphill, both ways! Look, there are three problems, all interrelated: 1) Documentation seriously lags development. This is typical of software in general, but community developed software seems even worse. I see the Zope book as a good 2.2 book, with add-ins to update it to 2.4+. It is unfortunate, but natural, that the ZPT documentation was done as an add-on. Ideally, ZPT would be presented before DTML. 2) The documentation has historically been extremely focused on "how to", not "when to" or "why to". Again, this is fairly natural. First, no one wants to insult someone else by "teaching his grandmother how to suck eggs". Also, much of zope is somewhat novel, and it is taking a bit of time for "best practices" to develop. I think that you will see the next version of the Zope Book offering a bit more advice about "why to". 3) Third party products - there is little consensus on which products are, in fact, good. Every product developer tends to think that his is best! (And in fact, it usually is, for _his_ problems.) For example, I still use LocalFS, despite looking at several alternatives. The alternatives simply do not do what I need! It would be nice for Zope to have a developer/maintainer registry, like Debian's, with a way to mark a package orphaned, and a way to adopt a package, but I can certainly understand whay Zope Corp has not doen this, to date. (It adds a barrier to entry, it is a bureaucratic solution, it is a small constant irritant to everyon involved, at best) Jim Penny Jim Penny
participants (3)
-
Breuer, Yvon -
douwe＠oberon.nl -
Jim Penny