[Zope-dev] How to write to mailing lists. Was [Zope-dev] ZPatterns based CD example. example.

[Steve Alexander]

Hi James,

I'd really like to help you out with ZPatterns. However, I'm finding it
very hard work to make sense of your emails to zope-dev.

I only have a certain amount of time to keep up with mailing lists, and
so I usually just skip messages that are hard to read. I'm replying to
the list as well, and I hope you don't mind. I'm hoping that it might
give others some hints on writing easily understood emails.

Please understand that I really want to help with the software. This is
the essential first step towards that.


With that said, let's take a look at your message.

James Johnson wrote:
> 
> another person had this problem earlier.  It may have been because
> they used quotes like <dtml-var "foo">. It should be <dtml-var foo>.
> I get the same keyerror on foo?. I actually had ended up with the
> code you just gave from previous post. There must be a problem if
> others have had keyerrors.  My understanding is that by placing the
> skinscript in the specialist would be a blackbox thing and placing it
> in the specialists rack with the other providers would be a whitebox
> thing.  So seeing that the index_html is a method of the Class folder
> is should  "see" the artist property. So I need to call the
> specialist and do a propertyMap() or something on it first? What
> could cause a keyerror? Seems to me that myPPS has no keys because
> its empty. I'm using win98,winNT4, win2000, redhat 6.2, zope 2.2.1,
> ZPatterns 4.2.2Alpha or the latest. I to work all of the platforms.
> For the most part it's going to to be the win98 platform I'm
> developing on. I can't wait to pump out my first ZPattern product.


You've sent the email as one big paragraph. I can read it better if you
can separate it out into several paragraphs that form chunks of related
information. The information is tightly coupled within a paragraph; the
paragraphs are related to each other less strongly. This is just like
writing good software.

Let's look through your message bit by bit. Here, I'll try and answer
your questions.

> another person had this problem earlier.

You didn't quote any context from previous messages, and just started
the message with a reference to "this problem". Well, there may be a few
different problems going on, all at once. In some senses, they might be
the same problem, but seen from different angles, or viewed at different
levels of abstraction. 

For example, sometimes I might ask for help with a problem. I think I
have a syntax error in my code. However, whilst it is true that I have a
syntax error, people are able to also tell me that I'm going about
something in a way that is unnecessarily complex.

The answer is to quote a few lines from the email you're replying to,
and also to restate the problem so that it is clear to everyone exactly
what it is you are talking about. This is also an opportunity to clarify
your own thoughts on what seems to be going on with your software. I
find this step invaluable, and sometimes, the extra clarity I get from
it shows me something I missed before, and I end up solving the problem
myself, and sharing a successful solution with the mailing list.

> It may have been because
> they used quotes like <dtml-var "foo">. It should be <dtml-var foo>.

When you're talking about code, you should include a small example, even
if it means pasting it in from a previous email. Otherwise, I can't tell
whether what you say makes sense.

In what you have written, above, I can't tell whether <dtml-var "foo">
or <dtml-var foo> is best. In general, I use both of those forms, and
others, in different situations. There is always a reason why I'd use
one or the other.

> I get the same keyerror on foo?.

Is this a question that you want me to answer? Actually, I don't
understand what you are saying or answering here. If you get an error
from some code, and you want people to help you understand why you get
the error, you should include all the code that causes the error.

If there is a lot of code, take the time to produce a small example that
exhibits the same error. Then, others can easily try out what you have
done, and it's more likely that someone will be able to help you with a
solution.

Also, if you get an error, and you don't understand why, include the
name of the error, and the error value that Zope tells you. Also,
include the traceback.

An error doesn't just occur on its own. It is part of a story, and it
only occurs when you do things a certain way. In order for people to
understand what you have done to get the error, you need to tell the
story.

Start by saying what the versions of software on your system are, as
some problems are caused by using old or incompatible software. I see
you've done that below. It is generally better if it is at the start, as
it gives your readers some context for reading the rest of the story.

Next, explain briefly what you are trying to do. If you don't do this,
some of the answers people give won't apply in your circumstances. As a
silly example, if I thought your goal is to have a bug-free Zope system,
and you are having problems with ZPatterns, I could recommend that you
just erase ZPatterns, and all the related objects. There, problem solved
:-)  But, even in less silly examples, readers need to know what you
want to achieve.

Ok, so you've described your Zope installation, and you've stated
clearly and briefly what it is you're trying to do. Next, tell the story
of how you have got to the point that the error occurs, and try to
explain why you chose to do it the way you did. Again, this helps people
to make suggestions that will work for you.

For example:

"I want to make a CD library using ZPatterns. This is some software that
allows me to store the names and tracks of the CDs I own, search for a
particular CD by name or track, and browse them in alphabetical order.

"First, I created a ZClass called CD that is derived from DataSkin and
ObjectManager. Then I created another ZClass called Track that is just
derived from DataSkin. I checked the box to say that they should be
derived from the usual base classes for persistence. I created both
inside a Product I called CDLibrary. The CDs will live under a
customizer folder, in subfolders representing styles of music, and the
tracks will be sub-objects of the CDs.

"Next, I created a Folder w/ Customizer Support in the root of my Zope,
called CompactDisks. I went to its Customizers tab, and added a
customizer called customize_cds and another called customize_tracks."

Keep going until you have described what you've done and why, and what
you did to get the error, and what you were trying to do when you got
the error.

Errors are tricky things, and sometimes they're caused by something you
did, or something you didn't do and should have, in a different part of
the system than you were working on when you first saw the error.

> I actually had ended up with the
> code you just gave from previous post.

That's great. Where did you put it? Did it work? Was it exactly the same
code? It is usually best to post small examples of the code you're
using.

> There must be a problem if
> others have had keyerrors.

I'm confused here. What do you do to make a keyerror occur?

> My understanding is that by placing the
> skinscript in the specialist would be a blackbox thing and placing it
> in the specialists rack with the other providers would be a whitebox
> thing.

Well, that depends. One way of looking at it is that Data-PlugIns that
you put in a Rack apply only to Objects stored in that Rack, whereas
Data-PlugIns that you put directly in the specialist apply to all the
objects in all the Racks in that specialist.

Racks are mostly about storage. So, I'd put SkinScript that is to do
with storage in Racks. However, cataloguing objects' metadata in a
ZCatalog is something you'd want to do regardless of how something is
stored, so I'd generally put a CatalogTrigger in the Specialist. Also,
if you wanted to be sent an email whenever on object in the specialist
is deleted, well, put some SkinScript in the Specialist for that. Of
course, the SkinScript can't send an email; it'll call a different
method for that.

> So seeing that the index_html is a method of the Class folder
> is should  "see" the artist property. So I need to call the
> specialist and do a propertyMap() or something on it first? What
> could cause a keyerror? Seems to me that myPPS has no keys because
> its empty.

I can't make much sense of this paragraph. Be wary of using
abbreviations like myPPS, and assuming that readers will understand what
kind of object it is. 

When you are asking a question, don't ask it as a statement; it is
difficult to know exactly what the question means to you.

> So I need to call the specialist and do a propertyMap() or something
> on it first?

If you mean "Do I need to call the propertyMap method of the specialist
before... ?", then say that. And when you say "...on it first?" I'm not
sure what you want to achieve by calling propertyMap(), so I don't know
what you'd want to do after calling it.

Sometimes it is useful if you can instrument your code. That is, you
print out the value of particular variables at various points in your
program. You can then say "I call method foo of the specialist, and I
expect to get back a PropertySheet, but it returns None instead."

A clear way of describing a problem is to say what you expect to happen,
and what really happens, and how they two are different.

> I'm using win98,winNT4, win2000, redhat 6.2, zope 2.2.1,
> ZPatterns 4.2.2Alpha or the latest. I to work all of the platforms.
> For the most part it's going to to be the win98 platform I'm
> developing on. 

Ok. This really belongs earlier on, but I'm glad you've included it
anyway.

In this case, I think you only need to say what version of Zope and what
version of ZPatterns you're using. However, if you're being complete,
state your operating system, and its version, the version of Python
you're using, and whether you installed it as a binary, or from source,
the version of Zope, and whether it is from a binary or from source, and
the version of ZPatterns.

When you talk about the operating system, say just what operating system
you are using to do your development on right now. If you are really
simultaneously working and testing on Windows 98, NT4, 2000 and RedHat
linux 6.2, then that's fine. Otherwise, just say the system you're
actually getting the error on.

> I can't wait to pump out my first ZPattern product.

This stuff should be fun. Looks like you have a positive approach to
learning this stuff. Great!

If you have an IRC client, you might want to drop in on irc.zope.net
#zope sometime. Various people who are knowledgeable about Zope and
ZPatterns use IRC there from time to time. Sometimes they'll have time
to help out with problems.

--
Steve Alexander
Software Engineer
Cat-Box limited
http://www.cat-box.net