[ZDP] ANNOUNCE: Zope Tutorial 1.0a3

[Amos Latteier]

> Comments on Amos' Tutorial Material
> 
>   First, boy, the URL to access it the tutorial is pretty buried!
>   Obviously people will do something closer to "click on help, then
>   click on tutorials", right?

Right. The tutorial (and the help system) will ship with the next major
version of Zope. It will be easy to get to the tutorial, and no
installation or typing in URLs will be necessary.

>   The tutorial doesn't have much of a cover page, something that
>   explains how tutorials work, who they are for, etc.

Yes, the tutorial needs some explanation of what it is, how it works,
and who its for.

>   Obviously the presentation in HTML is pretty bland, it's just the
>   default rendering.  Is it a goal of the tutorials to have them be
>   visually engaging, a la XML.com articles?

Not really, but it would probably be a good idea.

>   It's important to let people know how many more lessons there are.

Yes, but I imagine that you don't have to do all the lessons if you
don't want to. There should be some way to skip around or come back to
the tutorial later.

>   Is there some way to avoid discussion of 'index_html'?  Can you just
>   make it 'home.html'?  Since few have ever seen the '_html' style,
>   they will be presented with a new concept.  Though (until we fix
>   Zope) they'll need to know about 'index_html', that Zen should be
>   postponed.  They should be kept close to what they already know.

'home.html' seems fine.

>   On '1. Change the...' the line ends with a double colon.  Structured
>   text should have converted that to a single colon for display,
>   right?

It never seems to do that for me :-(

>   Near the top of Lesson 1, you have 'First you need...'  In that line
>   you have 'DTML Documents' with the 's' in documents as part of the
>   fixed font.  It implies that the 'DTML Documents' is a concept,
>   rather than 'DTML Document'.  Later under Summary you do the right
>   thing, having _DTML Document_s for a hyperlink.
> 
>   Man, this is good.  The use of a glossary is just earth shattering.
>   Is the glossary associated with the help system _globally_ (hope
>   so!) or just with the tutorials?  I'd like to see a central glossary
>   in the help system.

It is not currently a global facility of the help system. It could be,
though.

>   Change the last paragraph to something like:
> 
>     Congratulations, you've created a web page with Zope.  In the next
>     step,
> 
>   That is, set the scene briefly for the next page.

Good idea.

>   Perhaps it's just me, but the navigation buttons seem oddly placed.
>   I wonder if they should be left justified.

Whatever.

>   In Lesson 2, the first paragraph has a grammar error. How about:
> 
>     Elvis loved his home, Graceland. Let's link an existing 
> page to our
>     web site with information about Graceland.

Done.

>   I think the Lesson 2 page should reiterate the explanation of DTML
>   tags.

Good idea. I think in general the tutorial should repeat and complicate
ideas that are introduced earlier.

>   A note at this point.  The text is extremely terse, as opposed to an
>   XML.com article.  Does everybody think that this is the right
>   approach?  I do, but more feedback is appreciated.

I agree. I think more detail is needed, but elsewhere. The glossay is a
start, but How-Tos and the Guides should be the locaion of the real in
depth discussion.
 
>   I think that 'id' and 'title' should be glossary entries.  In the
>   'id' entry you can explain the rules for valid characters.  In
>   'title', you can explain that it is optional, and 'title_or_id' is
>   the preferred way to access it.

OK.

-Amos

--
Amos Latteier         mailto:amos@digicool.com
Digital Creations     http://www.digicool.com