[ZDP] Re: ZDP tutorial comments and integration proposal

[Rik Hoekstra]

>Sorry for the slow response. I've been moving offices and have just
>gotten my email set up again.

OK, no problem (just wondering where you'd gone ;-))
>
>> More importantly, we think there should be an
>> integrated package with a Zope Quickstart.
>
>I agree.
>
>> Some of this is
>> already covered
>> in your Tutorial Notes at
>> http://www.zope.org/Documentation/Projects/Tutorial/TutorialNotes
>>
>> Below I have put together some of the remarks on the list.
>> Most of them are
>> from Maik Roeder, Chris Withers and myself, so don't keep the
>> whole ZDP
>> group responsible ;-)
>>
>> I started with a very subtle comment on the the tutorial:
>>
>> For an introduction, the tutorial (which is basically a
>> canned hands-on
>> session) is not enough. Newbies also need some more theoretical (read:
>> higher level, conceptual) texts to get them acquainted with
>> Zope and it's
>> (basic) concepts: what is dtml, what can I use it for, how?
>> What are all
>> these objects I can choose from. I have a sql database, can I
>> connect it to
>> Zope? How? And once it's connected?. Believe me, I have seen
>> people struggle
>> with this.
>
>Right. The tutorial doesn't try to answer people's questions. It doesn't
>tell you Zope's features. It shows you how to start using Zope.


yep

>
>> Moreover, as far as I have seen it, first time users stumble
>> blindly through
>> the tutorial, they do not know what is happening, have little
>> affinity with
>> the subject and do not care what is happening (sorry if this
>> sounds harsh).
>
>I disagree. But I can see your point. Folks who want their questions
>answered and don't want to explore will be unhappy.

OK, that probably better captures what we meant.

>
>> Maik remarked he already tried to acoomplish this in the ZDP
>> Portals (did
>> you have a look at them at the ZDP site?). For example, the beginners
>> portals should cater prospective users and newbies with all sorts of
>> backgrounds: an Administrator with some Apache background should find
>> exactly how he can use Zope to make it work with Apache. Now,
>> we know (as
>> probably no one else knows) that much of this information is
>> hanging out
>> somewhere in HowTos, guides, ZDP documents, bundled Zope
>> documentation, but
>> it should be findable, hence our plea for an integration.
>
>I agree with your desire for integration.
>
<snip>

>>
>> MacroMedia Authorware has a usable concept in help/tutorial. They have
>> reusable, annotated and extensible pieces of software for key
>> tasks and a
>> higher level description how to integrate them. In this way
>> the tutorial
>> could be extended (which is not too far off your Tutorial Notes).
>
>Sounds good though I am bit unclear on what this means.


Hm, so am I, but I have some vague notions. Ideas anyone?

<snip>

>> More details of our summary can be found at:
>> http://www.zope.org/Members/chrisw/ZDP/NewUserPortal
>>
>> This will only work if it is integrated with the tutorial.
>> That's why this
>> mail - what are your thoughts, what are your comments, how
>> can we cooperate most usefully?
>
>I see a couple issues:
>
>  1. You correctly point out that the tutorial is not sufficient for
>folks to learn Zope.
>
>My working notion is that the tutorial is supplemented by a number of
>resources:
>
>  * Official Guides and Refs
>  * ZDP and other community docs like Zope.org how-tos


Let's take developments in documentation into consideration (today I was
talking with Martijn Pieters on this at WWW9, so some things from there as
well):

- I personally like the guides, but there are people who can't grasp Zope
with them
- As Martijn (you don't mind me quoting you, do you ;-)) remarked:
documentation is very much _explanation_ oriented. If you want to _know_
about Zope and how to program it, there is nothing there but the source. The
Interfaces project is addressing this part. I am confident it will result in
good documentation for developers.
However, this does not take care of the people who start using Zope. Or, to
put it another way: explanation is typically pointed toward _specific_ parts
of Zope. And what is there to explain if you do not have questions yet,
except the most general. To rephrase this once again: As Zope is a total
package, documentation can only start with a holistic overview, not by a
part to part explanation, as this will only add to the confusion.

(Travelling back and forth to WWW9 I started to scribble down some
documentation that I think (or rather hope) will cater this need. I'll try
and find time to type that out in the next days for an impression)


>
>I'd love to integrate sources of Zope documentation as much as possible.
>The ZDP portal seems like a great way to do this.


yep

>
>  * If you can suggest links that tutorial lessons should have to ZDP
>(or other) resources, I'd be glad to add them.


OK, but give us some time (sigh)

>
>  * If you'd like to include the Tutorial in some form on the ZDP portal
>I'd love that.
>

See above

>If there is something I can do to help this sort of cross linking, let
>me know.
>

You bet!

(I propose we continue discussions on the ZDP Wiki at
http://www.zope.org/Members/chrisw/ZDP)

Rik