[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 
- 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?



More information about the grok-doc mailing list