[Zope] Zope Documentation

[Breuer, Yvon]

Hi *,

I *really* think it's time to make a strong effort to get a better Zope=20
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=20
be done the best way...

Trevor Toenjes has made a very good 'beginning'! (Although beginning=20
probably isn't the best term for it.) Maybe it's sufficient to extend=20
his work with some ideas from Patrick Price. I'd like to ask you *all*=20
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=20
   '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=20
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*=20
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=20
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=20
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=20
> throwing together instructional pages like the Zope Tutorial?
> Something that could be used for ANY kind of tutorial, slide show,=20
> 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=20
> 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=20
> 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=20
> 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=20
> you even try to use this product.  In other words, not only show the=20
> *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=20
> 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=20
> restart the server *twice*.)  I *love* product pages that have=20
> 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=20
> how it was implemented in size-2 type or something.  Are you afraid =
I'll=20
> steal your design?  Hey, that's how I learn!   The ZDP comes to mind.=20
> How do they do that?  Is it mentioned on that page?  Nope. No, "this=20
> wiki based on wackproductZ and CMF".   I see so many nice web layouts=20
> and have *no* idea how they were done, what products were used, nada.  =
=20
> It's a shame.
>
> People learn stuff then take it for granted. =20
>
> 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=20
> > > > getting nervous about seeing all the things that I use fall=20
> > > > one-by-one into the "that's depreciated, use this other cool=20
> > > > product instead." I don't think I have a right to complain,=20
> > > > but I'm complaining any way :-)
>
> Charlie Reiman wrote:
> > > Technically, no, you don't have a right to complain but you do=20
> > > have a very good point. I'd like to echo it and point out the=20
> > > problem is exacerbated by zope.org not having a strong way of=20
> > > marking docs and products as deprecated.
> > > I hate finding a cool product, downloading and installing,=20
> > > only to learn it fell out of fashion with 2.something.=20
> > > Ideally, such pages should be marked and linked to whatever is=20
> > > 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