[Grok-doc] TASK: Review the official tutorial and make a list of improvements
Marc Rijken
marc at rijken.org
Wed Feb 24 08:44:42 EST 2010
Below you will find some suggestions for the official tutorial. I looked
mainly at a high levels: what is described and what is not described
yet. I have not used the tutorial to check all content in detail. I
think that can be done best when there is a new version.
Chapter 1
---------
- suite the tutorial for grok 1.1. I have not tested it with grok 1.1a2.
Maybe that needs to be done without the rest of the improvements in
order to get it ready before the release of 1.1
- describe the intended audience in more detail and the knowledge and
computer configuration a reader needs to have in order to use the tutorial
- describe the history and purpose of Grok in more detail
- the place of the sidebar with ZPT is not logical. It has to be placed
where ZPT are used first in the tutorial
Chapter 2
---------
- 2.1: describe distribute as replacement of setuptools
- 2.2/2.3: do not describe zopectl if that's not the preferred way. It
can be described in new chapter which tells more about the way grok
works, but not in this chapter, because it is not necessary for getting
started.
- 2.2 : common problems are important. Are there more common problems?
If so, make a new chapter with these.
- 2.3: describe how the serve can listen to another address than localhost
- 2.4 describe the directory structure in more detail in this paragraph
or a new chapter which describes the way grok works
- 2.4 describe the purpose of the directives in configure.zcml or do not
show the content of that file.
Chapter 3
---------
- great chapter
- maybe add something about JSON and traversing
- forms can be described in more detail in a new chapter.
Chapter 4
---------
- in this chapter forms are made manually. I do not think that is the
preferred way.
New content
-----------
- there are a few TDB which needs to be done
- make a chapter with all used main components and packages, a short
description and a reference for further reading. The rest of the
tutorial can be more lean when these components are not described in the
main tutorial anymore. For example ZPT (which is now described in
chapter 1), easy_install, virtualenv and zc.buildout (which are now
described in chapter 2), ZODB, evolution, etc.
- make a glossary
- make a new chapter which describes how Grok works, what the main
concepts are, etcetera. Interesting topics are: What is done (loaded,
grokked) at startup? What is done when a request will be handled?
- it can be convenient when the reference
(http://grok.zope.org/doc/current/reference/index.html) is integrated in
the tutorial.
- it can be convenient when the grok overview
(http://grok.zope.org/doc/current/grok_overview.html) is integrated in
the tutorial.
- some tutorials from http://grok.zope.org/feeds/all-howtos-tutorials
are improvements for the official tutorial.
Important Question
------------------
Before we start improving the tutorial, it is important to have
agreement over what to describe and what not. Do we want to create a new
Grok Book? Do we want to have one tutorial that contains all things a
normal grok user will need to know in order to develop with Grok? Or is
it just a first start document for the grok user and do the user need to
look further (on grok.zope.org, on the mailing lists, in the Grok Book,
etc) for more information?
Regards,
Marc
More information about the grok-doc
mailing list