[ZDP] ANNOUNCE: Zope Tutorial 1.0a3

[Paul Everitt]

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.