[Grok-doc] Request for mission statement for the grok tutorial

[Roger Erens]

On Wed, Mar 3, 2010 at 10:23, Sebastian Ware <sebastian at urbantalk.se> wrote:
> Marc Rijken has reviewed the Grok tutorial and posted suggested
> improvements. He raises an important question with regards to the
> scope of the 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?
> """
>
> In other words. What is the purpose of the Grok tutorial and how far
> should it guide a first time user?
>
> Mvh Sebastian

An option is to rename and improve it towards a 'Quick Start Guide'
and make it possible for 'ordinary Python programmers' to work their
way through that in one afternoon or evening. And then to have a 'User
Guide' that is more comprehensive, a la the Grok 1.0 Book. And
possibly thirdly, a 'Definitive Reference Guide' with all the gory
technical details.

And with this relationship:

all types of functionalities needed to compose a web application <-->
A single type of functionality

we might obtain these relationships:

QuickStart Guide <--> How-To
User Guide <--> Tutorial

That's a structure one sees often in other (reasonably) well-documented systems.

Regards,

Roger