YB: Maybe we shouldn't talk about a true way, but about a *preferred* way. DM: But your preferences are not necessary mine and mine even vary with context... I understand your examples and I see your point. DM: 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. I agree! DM: But I would welcome [1] 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, [2] 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. All I've been trying to achieve was to get an improvement on how to retrieve whatever you need for a certain goal. I think the current documentation isn't clear enough in this matter. I _do_ what I'm missing, but, because of my lack of experience, I didn't know (still don't) how it can be solved. While following the postings on the list I have the feeling this also applies to others. Maybe this improvement can be achieved by your [1] and [2] solutions! If others agree: Who'll set it up? (and how?) DM: PS: you could learn to strip your quotings down a bit. I'll try... ;-) Yvon PS: "If others agree" --> Because I think the community should support it to make it use- & succesfull.
I think there are good points raised here. Thanks for including me in the thread. It is interesting that Zope and community has created it's own Catch 22. This power is also a stumbling block. The power of having many options and approaches also creates confusion for the newcomer to navigate and determine the best choice of direction in learning and approaches toward solutions. The first steps to build your first Zope website often creates enough momentum to hinder the newbie from learning alternative approaches until much later. How many newbies think that the DTML_Document is that all powerful object because it is what is used in most examples with standard_html_header? And then proceed to create a website with 100% DTML_Documents, only to discover they have now defeated many benefits of acquisition and folders? And then you go back and convert everything to DTML_Methods with folders containing properties. This echoes my experience. I got so involved with the simplicity of DTML that it has taken me a long time to try and break the 'crutch' of using DTML for everything. A crutch is NOT good. When a newbie has a problem, the only choice is to search mail list archives and zope.org docs. But these are heavily laden with DTML references and can quickly send the newbie into the perception that DTML is everything in Zope, which just isn't the case anymore. I think it is a big mistake that the Zope Book consider p-scripts advanced. This should be considered a basic requirement for newbies. The community has long stated that newbies should be exposed to python scripting immediately. And I don't think we do a good job at that. It is too easy to become *mediocre* in DTML, which doesn't benefit the community by creating talented developers. The challenge on NZO will be to promote the flexibility of all the options as a positive attribute. Another approach could be to explain a quick overview of the options...almost like an introspective critique. We almost need a community endorsed comparison of DTML, p-scripts, and external methods and python products and the suggested appropriate situations for each. This comparison/overview could also serve as a warning to newbies that there are many choices and that some are more Zope-esque and others are more Python-esque. And the current wave is that python-esque promotes more flexibility, scalability and power. How is that for trying to address both sides? The hard work is sitting down to create this document. -Trevor Yvon, please help refine the Software Products GUI. We welcome all feedback and I would like to see how you want to apply your feedback to a solution.
-----Original Message----- From: Breuer, Yvon [mailto:YBreuer@tee.toshiba.de] Sent: Monday, August 12, 2002 5:03 AM To: Dieter Maurer Cc: zope@zope.org; douwe@oberon.nl; zope@toenjes.com; jprice22@wvu.edu Subject: RE: [Zope] Zope Documentation
YB: Maybe we shouldn't talk about a true way, but about a *preferred* way. DM: But your preferences are not necessary mine and mine even vary with context... I understand your examples and I see your point.
DM: 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. I agree!
DM: But I would welcome [1] 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, [2] 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. All I've been trying to achieve was to get an improvement on how to retrieve whatever you need for a certain goal. I think the current documentation isn't clear enough in this matter. I _do_ what I'm missing, but, because of my lack of experience, I didn't know (still don't) how it can be solved. While following the postings on the list I have the feeling this also applies to others. Maybe this improvement can be achieved by your [1] and [2] solutions! If others agree: Who'll set it up? (and how?)
DM: PS: you could learn to strip your quotings down a bit. I'll try... ;-)
Yvon
PS: "If others agree" --> Because I think the community should support it to make it use- & succesfull.
The first steps to build your first Zope website often creates enough momentum to hinder the newbie from learning alternative approaches until much later. How many newbies think that the DTML_Document is that all powerful object because it is what is used in most examples with standard_html_header? And then proceed to create a website with 100% DTML_Documents, only to discover they have now defeated many benefits of acquisition and folders? And then you go back and convert everything to DTML_Methods with folders containing properties.
Note that this practice is explicitly denounced in the new Zope Book edition. As a matter of fact, I go so far as to say that people should probably *never* use a DTML Document. This is in the introduction to DTML.
When a newbie has a problem, the only choice is to search mail list archives and zope.org docs. But these are heavily laden with DTML references and can quickly send the newbie into the perception that DTML is everything in Zope, which just isn't the case anymore. I think it is a big mistake that the Zope Book consider p-scripts advanced. This should be considered a basic requirement for newbies.
Good point.
We almost need a community endorsed comparison of DTML, p-scripts, and external methods and python products and the suggested appropriate situations for each.
FWIW, I try to do this in the docs (see http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/BasicObj ect.stx).
How is that for trying to address both sides? The hard work is sitting down to create this document.
Weel, forgive me for having a one-track mind, but it's already in motion if you're willing to live within the constraints of the Zope Book. I think this is its main purpose, as folks need a sanity check when they first come in to Zope. The ZB can help to do this because it's highly organized, it has a controlled scope, and it has at least a little bit of momentum (FWIW, I have spent ~ 200 hours editing it for 2.6 and a few other people have contributed time and effort as well). NZO can help people *find* the Zope Book and other critical documents, help people make decisions about which third-party products are "good" and which are bad, and help folks better categorized HowTos, all of which are problems that need to be solved that are not even close to being solved by the current docset. - C
DAMN BOY!! You are on top of things. I will crawl back in my hole. ;) You are doing some good things with the Zope Book. Releasing 2.6 docs before the final 2.6.1 is VERY impressive. lol. is there going to be one? And you have a point, that the online Zope Book could be the place to reference in many of the NZO requirement areas. And if the ZBook has the answer then we should utilize it rather than recreating the wheel. The proposed Software Product GUI goes a long way toward organizing community released products and organizes product specific how-tos in that area. hmmm, now you have me thinking that how-tos should be categorized as Zope, non-specific scripts, and Product specific. -Trevor
-----Original Message----- From: zope-admin@zope.org [mailto:zope-admin@zope.org]On Behalf Of Chris McDonough Sent: Monday, August 12, 2002 4:06 PM To: Trevor Toenjes; Breuer, Yvon; Dieter Maurer; Sidnei@X3ng. Com. Br Cc: zope@zope.org; douwe@oberon.nl; zope@toenjes.com; jprice22@wvu.edu Subject: Re: [Zope] Zope Documentation
The first steps to build your first Zope website often creates enough momentum to hinder the newbie from learning alternative approaches until much later. How many newbies think that the DTML_Document is that all powerful object because it is what is used in most examples with standard_html_header? And then proceed to create a website with 100% DTML_Documents, only to discover they have now defeated many benefits of acquisition and folders? And then you go back and convert everything to DTML_Methods with folders containing properties.
Note that this practice is explicitly denounced in the new Zope Book edition. As a matter of fact, I go so far as to say that people should probably *never* use a DTML Document. This is in the introduction to DTML.
When a newbie has a problem, the only choice is to search mail list archives and zope.org docs. But these are heavily laden with DTML references and can quickly send the newbie into the perception that DTML is everything in Zope, which just isn't the case anymore. I think it is a big mistake that the Zope Book consider p-scripts advanced. This should be considered a basic requirement for newbies.
Good point.
We almost need a community endorsed comparison of DTML, p-scripts, and external methods and python products and the suggested appropriate situations for each.
FWIW, I try to do this in the docs (see http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/BasicObj ect.stx).
How is that for trying to address both sides? The hard work is sitting down to create this document.
Weel, forgive me for having a one-track mind, but it's already in motion if you're willing to live within the constraints of the Zope Book. I think this is its main purpose, as folks need a sanity check when they first come in to Zope. The ZB can help to do this because it's highly organized, it has a controlled scope, and it has at least a little bit of momentum (FWIW, I have spent ~ 200 hours editing it for 2.6 and a few other people have contributed time and effort as well).
NZO can help people *find* the Zope Book and other critical documents, help people make decisions about which third-party products are "good" and which are bad, and help folks better categorized HowTos, all of which are problems that need to be solved that are not even close to being solved by the current docset.
- 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 )
DAMN BOY!! You are on top of things. I will crawl back in my hole. ;)
Please dont! ;-)
You are doing some good things with the Zope Book. Releasing 2.6 docs before the final 2.6.1 is VERY impressive. lol. is there going to be one?
Well, luckily the book isn't finished either. ;-)
And you have a point, that the online Zope Book could be the place to reference in many of the NZO requirement areas. And if the ZBook has the answer then we should utilize it rather than recreating the wheel.
Yup...
The proposed Software Product GUI goes a long way toward organizing community released products and organizes product specific how-tos in that area. hmmm, now you have me thinking that how-tos should be categorized as Zope, non-specific scripts, and Product specific.
Coming up with a howto taxonomy is not easy... but I think you should just go for it! ;-)
OK. I have one final request before we really solidify the Zope Book as an integral part of the NZO project. For convenience, Talkback really needs to make the use of bookmarks in each chapter easier. It is not even obvious that it has bookmarks. And therefore no one can really reference sections of the Zope Book. 1. It should be obvious that "Using Object Properties" location is http://www.zope.org/Documentation/Books/ZopeBook/current/BasicObject.stx#2-4 3 without reading the HTML source. How about having the <h2> titles in a table at the top of every Chapter with their respective <a>nchors? 2. And the placement of the <name> id's need to be before the <h2> headers so the bookmark doesn't skip the title to display the following paragraph. 3. Can we put a hot spot near each section headline so a mouseover displays the URL with the bookmark so people can reference it in Documentation? Either use CSS to make the whole title an anchor to itself using a.h2 {text-decoration: none.} or put some other more obvious object near the headline. 4. And we need to shorten the URL length. Documentation/Books/ZopeBook/current kills an email link by wrapping it and makes the URL unusable. Can we just make the location www.zope.org/ZopeBook and this will be the location for the current version. Now, I havent put in full thought of the persistence of these links for archive references, but I imagine that the bookmarks don't change. My guess is you only add to them. And I don't think it is important that the <name>'s make any serialized sense. But I have noticed you are moving chapters around which does affect the URL. So maybe we need some error handling. But non-existent bookmarks don't produce a 404. So it would be convenient if you could inspect the QUERY_STRING to capture the "#foo" name request and try and resolve it with a redirect if it doesn't exist in the requested page. So any URL request with a bookmark has a chance to resolve to the intended location, even if the URL is incorrect (mostly to make room for a new chapter). Did this make sense? -Trevor
-----Original Message----- From: Chris McDonough [mailto:chrism@zope.com] Sent: Monday, August 12, 2002 4:42 PM To: Trevor Toenjes; Breuer, Yvon; Dieter Maurer; Sidnei@X3ng. Com. Br Cc: zope@zope.org; douwe@oberon.nl; zope@toenjes.com; jprice22@wvu.edu Subject: Re: [Zope] Zope Documentation
DAMN BOY!! You are on top of things. I will crawl back in my hole. ;)
Please dont! ;-)
You are doing some good things with the Zope Book. Releasing 2.6 docs before the final 2.6.1 is VERY impressive. lol. is there going to be one?
Well, luckily the book isn't finished either. ;-)
And you have a point, that the online Zope Book could be the place to reference in many of the NZO requirement areas. And if the ZBook has the answer then we should utilize it rather than recreating the wheel.
Yup...
The proposed Software Product GUI goes a long way toward organizing community released products and organizes product specific how-tos in that area. hmmm, now you have me thinking that how-tos should be categorized as Zope, non-specific scripts, and Product specific.
Coming up with a howto taxonomy is not easy... but I think you should just go for it! ;-)
For convenience, Talkback really needs to make the use of bookmarks in each chapter easier. It is not even obvious that it has bookmarks. And therefore no one can really reference sections of the Zope Book.
1. It should be obvious that "Using Object Properties" location is
http://www.zope.org/Documentation/Books/ZopeBook/current/BasicObject .stx#2-4
3 without reading the HTML source.
Unfortunately, these numbers change as paragraphs are added and removed from the document, so they're not reliable as permanent links (unless the document doesn't change, which it does as the result of comments). I think we're going to have to punt here and say "see chapter foo, search for bar", because I'm not going to be able to create permanent link targets for each paragraph any time soon. It's a two-step process... make link targeting work in BackTalk then (perhaps manually) edit all the chapters to include permanent link targets. It's just not possible for me to do this right now (time-wise). If someone else wanted to take it on, I'd say yay and urge them on fervently from the sidelines. ;-)
How about having the <h2> titles in a table at the top of every Chapter with their respective <a>nchors?
This might work but note that the Book is composed entirely in structured text, so it's not just a matter of including HTML, it needs to be written into the framework. "Punting" and using HTML in the book source would be might be OK, but I'd feel dirty afterwards, and it would be confusing to folks reading the (as-yet-nonexistent-but-promised) text-only version. ;-)
Can we just make the location www.zope.org/ZopeBook and this will be the location for the current version.
Err, not really, unfortunately. The containment structure (and thus the URL) is necessary for versioning the book and BackTalk generates absolute URLs for chapters (by design). Note that you *can* get to any Zope Book chapter as well right now via links like http://www.zope.org/Documentation/ZopeBook/ChapterName.stx as well, but it will just redirect you to the longer URL for the chapter. How about http://makeashorterlink.com ? I agree this is annoying but it's not high on my "must fix" list. ;-)
But I have noticed you are moving chapters around which does affect the URL. So maybe we need some error handling. But non-existent bookmarks don't produce a 404. So it would be convenient if you could inspect the QUERY_STRING to capture the "#foo" name request and try and resolve it with a redirect if it doesn't exist in the requested page. So any URL request with a bookmark has a chance to resolve to the intended location, even if the URL is incorrect (mostly to make room for a new chapter).
I actually have been very careful to not remove any chapters but this is something that will need to be addressed soon, you're right. But not now. ;-) I dont mean for this to sound negative at all, I really really appreciate all of the input... I'm just incredibly time-strapped at the moment, so I can't in good faith promise anything beyond what already exists. If anyone wanted to spelunk BackTalk (http://backtalk.sourceforge.net) to add these features, I'd love to see them. - C
Chris McDonough writes:
.... ... because I'm not going to be able to create permanent link targets for each paragraph any time soon. It's a two-step process... make link targeting work in BackTalk then (perhaps manually) edit all the chapters to include permanent link targets. You may use the section titles as anchor names, then they might be automatically creatable.
Dieter
participants (4)
-
Breuer, Yvon -
Chris McDonough -
Dieter Maurer -
Trevor Toenjes