[ZDP] ANNOUNCE: Zope Tutorial 1.0a3
Paul Everitt
Paul@digicool.com
Sat, 15 Apr 2000 09:30:59 -0400
Amos wrote:
> I've revved the Zope Tutorial again. Now the RDBMS lesson
> should work.
>
> http://www.zope.org/Documentation/Projects/Tutorial
>
> I'd like to know if anyone has problems installing and using the
> tutorial.
Ugh, it's a shame that the ZDP isn't providing much feedback on this.
ZDP crowd, do you think Amos should keep with his policy of asking you
for comments before going to the main Zope list?
Anyway, here's the beginning of my comments.
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?
The tutorial doesn't have much of a cover page, something that
explains how tutorials work, who they are for, etc.
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?
The jump into Lesson 1 is pretty jarring. Where did "Elvis Lives"
come from? Perhaps a single page that sets the scene about the
fictional organization, then describes the kinds of things needed in
the site.
I like having the code boxes be in a different color.
It's important to let people know how many more lessons there are.
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.
On '1. Change the...' the line ends with a double colon. Structured
text should have converted that to a single colon for display,
right?
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.
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.
Perhaps it's just me, but the navigation buttons seem oddly placed.
I wonder if they should be left justified.
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.
I like that you chose 'graceland' for the folder id instead of
'Graceland'. I wonder if camel case in Zope should be a style that
is deprecated.
I think the Lesson 2 page should reiterate the explanation of DTML
tags.
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 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.