[Zope3-dev] PyCon DC 2003: Call For Papers

[Guido van Rossum]

> I see. Good to know. I still would like to comment on it as soon as I know 
> what is going to be changed. I know I like at least a couple of things 
> already, seing your checkins.

Here's what I know.  The first two rules are derived from Twisted's
rules:

- Module and package names should be short and lowercase.  Motivation:
  you'll never again confuse a class with its module.

- Modules should contain more than one class (a rule designed to be
  broken :-).  Motivation: this way the presentation order of classes
  (whether top-down or bottom-up) can help the reader to understand
  what's important; and it clarifies what classes (or functions) are
  related.  Compare to trying to find where to start in a directory
  full of classes, listed alphabetically.

- Special case: all interfaces go in "interfaces.py".  Motivation: see
  previous bullet.  (We tried thinking of a shorter name, but rejected
  abbrevs and "api.py" is wrong, since quite often several interfaceds
  are more internal than part of the API.  Also it's still an abbrev,
  even if a very common one.)

- Since the above rules greatly reduce the number of files, there's
  much less need to create subdirectories for certain classes of
  files.  In particular, it seems that views can happily live in the
  main package directory, rather than in a subdirectory named by
  category (e.g. "browser").  (Note that we already decided not to
  group all views in a "views" subdirectory.)  I imagine that if a
  product has a large number of e.g. images or ZPT templates, they
  could still go into a separate subdirectory, at the product
  designer's discretion, but if you have just a few, that's not
  required.  I found that having only one configure.zcml for a project
  rather than a main one and one for "browser" related configuration
  reduces the amount of configuration boilerplate (there's enough of
  that already :-).

> > I can't speak for Jim there, but it can't always be done that way.
> > Burocracy exists to support coding, not the other way around.
> 
> Mmh, in my opinion it is not just burocracy; I usually start at the
> original proposal of a feature, when I try to write documentation
> for it, since the proposal usually discusses the motivation and
> shortcomings of the feature (for example), which is always helpful
> when writing docu.

We used the shortcut of having several people in the same room
discussing the project.  This works quite well as long as you write
things down afterwards.

> > We discuss proposals extensively at the sprint -- explanations for
> > the rest of you (all two of you :-) will come later.
> 
> :-) I think it is a couple more (Codeworks has 4 gals/guys, Sidnei,
> David and me).
> 
> > You can help by asking specific questions rather than requesting that
> > we document/explain everything that's done.  What do you want to know?
> 
> Sure, the reason why I made this request was the following: After
> many sprints we noticed that peopl did not keep working on the
> projects and abondened them. Since noone really knew the stuff was
> there or at which state it is, it was hard to pick it up.

Well, you can't avoid people abandoning projects. :-(  I doubt they
would have done better if forced to document what they did. :-(

> So here are my questions (in this case specifically for the
> documentation group, since I am trying to organize this effort):
> 
> - What did the guys work on? I saw a README.txt to be checked in,
>   but does that mean that most packages should get one? Is there
>   such though?
> 
> - Was anything else discussed regarding Documentation? 
> 
> - What are the chances that these guys will work on Documentation
>   after the sprint? 
> 
> I guess we do not need so much a proposal than a Sprint log...

Last night I wrote several pages of diary about my project so far (the
text index).  I can purge it of personal remarks and post it here, or
on the website.  It would take me an hour to edit probably.  Is that
worth it?

--Guido van Rossum (home page: http://www.python.org/~guido/)