[Zope] Zope Documentation

Fri, 9 Aug 2002 11:22:49 +0200

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 )