[Grok-dev] thoughts while writing a tutorial

[Sebastian Ware]

I am thinking "proxy" as in you use them to access something else.

I think you should skip the boilerplate introduction. It would be  
better if we had a "howto set up a sample project with debugging and  
other useful stuff turned on" and start from there in the samples.


I know it is more semantics, but I think we should call them recipes,  
indicating that they should be kept lightweight and focused.

Howtos, to me, are ways of setting up an environment. Tutorials are  
more general and comprehensive.

Mvh Sebastian


17 aug 2007 kl. 05.31 skrev Brandon Craig Rhodes:

> Two weeks ago I promised a tutorial on using SQLAlchemy from Grok,
> after getting positive feedback about some example code I posted,
> which used a custom traverser to instantiate the ORM objects to which
> the user was trying to navigate.  Martijn mentioned that there was
> another possible technique for traversing: creating a custom container
> class.
>
> Martijn's comment made me realize that I actually need to write *two*
> tutorials!  The idea of traversing to an object that does not exist in
> the ZopeDB is a whole subject on its own, completely separate from the
> question of how one uses "zalchemy" from Grok.  Traversing to
> non-ZopeDB objects has all kinds of uses, from generating dynamic
> mash-ups to creating on-the-fly search results; and trying to explain
> custom traversal and custom containers at the same time as "zalchemy"
> would, I now think, get everything confused.
>
> So now I am busy writing a simple first tutorial on navigation to
> objects that are not persistent in the ZopeDB, but which are created
> on-demand when the user tries to look at them.
>
> Some questions have come up that I need guidance on.
>
>  - What should I call this sort of object?  Several names suggest
>    themselves, but I want to use just one main one through the
>    tutorial:
>
>     "On-demand objects"?
>     "Dynamic objects"?
>     "Non-persistent objects"?
>     "Non-ZopeDB objects"?
>     "Ephemeral objects"?
>     "Transient objects"?
>
>  - I note that every tutorial starts with boilerplate about
>    "easy_install grokproject" and running "grokproject" to create the
>    project and how to start the server and create a first instance of
>    the application.  Is repeating this information each time the right
>    approach?  Or should we have a short "Starting a Grok Application"
>    tutorial that the others can reference?  ("For this tutorial, start
>    by creating a Grok instance named 'Foo' whose application you
>    instantiate at '/footest'.  See *link-to-the-page* if you have not
>    yet learned how to do this.")
>
>  - Tutorial authors might like having a way to test-render their
>    tutorials before they submit them to see what they would look like
>    on the Grok site; that way, we can debug the refactored text and
>    see if our markup makes sense.
>
>  - It would also be nice to be able to "get back to" the refactored
>    text later once the tutorial is up on the web, so that we could
>    submit patches against our original texts as we continue to improve
>    them.  I know that I will want to continue improving the tutorial
>    as my understanding of Grok impoves!
>
>  - Why do we call them "tutorials" on the mailing list but "How-to's"
>    on the web site? :-)
>
> -- 
> Brandon Craig Rhodes   brandon at rhodesmill.org   http:// 
> rhodesmill.org/brandon
> _______________________________________________
> Grok-dev mailing list
> Grok-dev at zope.org
> http://mail.zope.org/mailman/listinfo/grok-dev