Re: [Zope] Keeping my promises - writing tutorials for Zope
What I would like to hear from everyone else is, what things should be covered and how, to which other resources and how-to's I should link to and -- the most important part -- ' Hey nice idea, I could write about this thing' or 'yes, I commented to the wiki just a couple of minutes ago'.
You are doing a wonderful thing. I would like to make a few suggestions... I've noticed that many people who start with Zope are coming familiar with basic web concepts and, more importantly, are coming from work on other application servers that, for whatever reasons, were not providing the functionality needed. Newbies need a context and a paradigm with which to work FIRST, before the other things begin to make sense. Aside from navigating (plus cut/copy/paste) in the management screen, the first thing would be: 1. Object Publishing (how to make an object appear on the web via a URL. That seems elementary, and it is. Moreover, there is some instant gratification and the hope that they can do something useful (and are not wasting their time). There is also a list of "common things" that people do on a web site that force the site builder to add certain functionality. Consequently, the newbie asks basic questions like "How to I list objects on the site?" How do I link to objects within the site? How do I list only _certain_ objects?" etc. What they want in those instances is a brief explanation and some sample code (sometimes they just want the code). Don't belabor the explanation. Be brief and just state how to do it. You can always add a link to documentation that explains it in full, if they are interested (most often, however, they won't be interested). The list of "how you do this and that" would form the bulk of your work, and would be a huge help to the newbie community (and a reference to those who are experienced but can't quite remember how to do it). The next chapters would be _intermediate_ explanations on fundamental issues, such as aquisition, security, etc. -- but in a way that adds only to the practical functionality of web sites. This is more in the line of "tips and tricks" as opposed to detailed explanations. Again, show functionality and only _link_ to the detailed explanations. The final chapters would be devoted to links to detailed documentation AND provide the various options available in Zope for solving problems, such as building things with ZClasses versus Products, CMF, etc. In short, the last section of the book is a road map of where to find other things in greater detail, with an explanation of what potential those solutions offer. That is what I would do. (More importantly, that is what I always wanted when I was a newbie.) Good luck and best wishes, Ron
1. Object Publishing (how to make an object appear on the web via a URL.
That seems elementary, and it is. Moreover, there is some instant gratification and the hope that they can do something useful (and are not wasting their time).
Amen! I've written a lot in the new Zope Book revision about what it means to "publish an object", which in turn led me to need to write to a chapter about object orientation. The original aim of the Zope Book was to provide "instant gratification" to its reads by way of introducing simple applications straight away. But I've found that, by far, the people who are reading and commenting on the book want more often to know *why* something is the way it is than how to do it once by example. So I've taken the book and added a few chapters to it, and added a lot more explanations of the examples and whatnot. As a result, however, people don't actually get to build an application until about the 5th chapter. I think this is ok. I think what is necessary to fill the gap here is a "Zope Cookbook" much like the Perl Cookbook, which isn't really narrative about "how to learn Zope", but narrative about "how to to X in Zope". It'd be cool if someone were to make a deal with Adam to use the contents of ZopeLabs.com as the basis for such a cookbook. -- Chris McDonough Zope Corporation http://www.zope.org http://www.zope.com "Killing hundreds of birds with thousands of stones"
Chris McDonough wrote:
Amen! I've written a lot in the new Zope Book revision about what it means to "publish an object", which in turn led me to need to write to a chapter about object orientation.
Sounds good!
I think what is necessary to fill the gap here is a "Zope Cookbook" much like the Perl Cookbook, which isn't really narrative about "how to learn Zope", but narrative about "how to to X in Zope". It'd be cool if someone were to make a deal with Adam to use the contents of ZopeLabs.com as the basis for such a cookbook.
There is definiteve need for Zope Cookbook! I would have wanted that agest ago and when I have talked with new Zope beginners, they seem to want one too. Code examples that show Zope concepts are really powerfull way to learn after the person has first understood some of the basics of Zope. It should just be done. Who could start doing such a project and how we all could help it to happen? -huima
Heimo Laukkanen wrote:
There is definiteve need for Zope Cookbook! I would have wanted that agest ago and when I have talked with new Zope beginners, they seem to want one too. Code examples that show Zope concepts are really powerfull way to learn after the person has first understood some of the basics of Zope. It should just be done.
Who could start doing such a project and how we all could help it to happen?
The best place for something like a Zope Cookbook would likely be on the freezope.org domain. You could set something up there. They can give you a domain like "cookbook.freezope.org" or "recipie.freezope.org" (assuming its not already taken). Then we could set up sample code along the lines that we were talking. However, unlike ZopeLabs, the interface would be set up along the lines of "What to do..." or some set of basic topics. Ron
Personally, I think the best way to get the ball rolling on a Zope cookbook is the following: - Clear your calendar for the next four months. - Buy 20 cases of your favorite beer and situate them in your fridge. - Shut yourself in a room. - Talk to Adam at ZopeLabs and make a deal with him. - Shut down your email access. - Cut off contact with your friends and family. - Download ZopeLabs' recipes. - Edit the recipes into a real, publishable book. I'm only half-joking. Producing worthwhile documentation is (unfortunately!) not a suitable-for-committee effort. It can be done in spare time, but it calls for one or two committed and dedicated people, three at the most. It's also not a software development project. The minute you start to build elaborate tools to get the job done, you're dead. You'll end up with at least one nice tool but no content. We have statistical proof of this. ;-) - C ----- Original Message ----- From: "Ronald L. Chichester" <complaw@hal-pc.org> To: "Heimo Laukkanen" <huima@fountainpark.org> Cc: "Chris McDonough" <chrism@zope.com>; <zope@zope.org> Sent: Sunday, July 28, 2002 12:24 AM Subject: Re: [Zope] Keeping my promises - writing tutorials for Zope
Heimo Laukkanen wrote:
There is definiteve need for Zope Cookbook! I would have wanted
that
agest ago and when I have talked with new Zope beginners, they seem to want one too. Code examples that show Zope concepts are really powerfull way to learn after the person has first understood some of the basics of Zope. It should just be done.
Who could start doing such a project and how we all could help it to happen?
The best place for something like a Zope Cookbook would likely be on the freezope.org domain. You could set something up there. They can give you a domain like "cookbook.freezope.org" or "recipie.freezope.org" (assuming its not already taken). Then we could set up sample code along the lines that we were talking. However, unlike ZopeLabs, the interface would be set up along the lines of "What to do..." or some set of basic topics.
Ron
_______________________________________________ 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 )
participants (4)
-
Chris McDonough -
complaw＠hal-pc.org -
Heimo Laukkanen -
Ronald L. Chichester