[Zope] Zope Documentation

Fri, 9 Aug 2002 11:48:43 +0200

Douwe wrote:
> I think there are two issues here at stake. One, the Zope=20
> documentation, which is actually quite ok. There's the book,=20
> there are a number of howto's and there is the source code,=20
> which is really readable.

I understand what you mean, but...
Why is it then that it regularly occurs that I see a question on the=20
mailinglist that gets an answer like: "You shouldn't use product A,=20
but B..."?=20
Followed by: "Because"
"it's no good..." or=20
"it's not maintained any more..." or=20
"with B you can also..." or=20
"in B you don't have to...".

> The second issue is the nature of Zope. Guido van Rossums dictum=20
> that there should be one perfect way to do something, doesn't fly=20
> for Zope and in that way Zope is more like Perl then Python.=20
> For one problem, there are lots of solutions, different products,
> different approaches, different programming languages (DTML,=20
> Page Templates, Python). There is no one true way. Some people=20
> 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.

Maybe we shouldn't talk about a true way, but about a *preferred* way.
I really think it's a damn pity to learn something, try it, have =
problems
and finally find out I'd better done it in another way.

That's not very encouraging. Don't you agree?

Best regards,

Yvon Breuer

> -----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 )