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

Marc Rijken marc at rijken.org
Wed Mar 3 05:45:20 EST 2010


I also think it would be great that we would have Quick Start Guide, a 
User Guide and a Reference Guide.

Because the Tutorial is mostly like a Quick Start Guide, lets get 
started with the Quick Start Guide first.

Goal of the Quick Start Guide can be:
Describe the history/background of grok in a few words, provide an 
overview of the capabilities and show on an easy way how someone can
- install grok
- develop with grok
- run grok

An outline of the Quick Start Guide can be:
1. Introduction
1.1 History
1.2 Overview / Concepts
2. Setting up a new application
2.1 Prerequisites
2.2 Installation / setup a grokproject
2.3 Running (bin/paster server deploy.ini, debug.ini, etc)
3. Developing: a few examples
4. Further reading


Marc

Sebastian Ware wrote:
> I really like the "Quick Start Guide" idea!
> 
> Mvh Sebastian
> 
> 3 mar 2010 kl. 10.49 skrev 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
> 
> _______________________________________________
> grok-doc mailing list
> grok-doc at zope.org
> https://mail.zope.org/mailman/listinfo/grok-doc



More information about the grok-doc mailing list