[Grok-dev] thoughts while writing a tutorial

[Kent Tenney]

On 8/17/07, Sebastian Ware <sebastian at urbantalk.se> wrote:
> What a great idea. These "trails" could be a great way to organise
> "recipes", "tutorials", "howtos", "primers", "best practices" you
> name it...

I like the 'trail' terminology.

It fits with 'how do I get there?'

It also fits with the idea that the answer to
'how do I get there?' begs the question
'where are you now?'

I can see documentation structured such that 'where are you now'
is a property of a user, it changes as they learn more, and the
trail to take changes accordingly.

I'm trying to come up new documentation techniques, since Zope3 is
so confounding to me, but I want it's power. I could read Philipp's book
20 times and still not see how it all fits together. The linear narrative
just doesn't work for me in this case. My latest tack is to work on a
set of 'minimals'  try to implement the smallest possible working examples
of a feature, a capability or a demonstration.

I'm also planning to save tracebacks as I do it. It seems like there could
be value in building a traceback database annotated with helpful words.

I also think there could be a method of graphically illustrating the
relationships
between files, classes, zcml, ... and the resulting webpage, log message,
tracebacks etc.

Inkscape seems to be the sweet app for this kind of thing, initially working
out how to draw rich explanations, eventually try to generate .svg with code.

Thanks,
Kent
>
> That would make it very accesible to users. Maybe we eventually would
> have volunteers responsible of maintaining each trail. And a
> beautiful timeline showing who contributed what and when...
>
> Mvh Sebastian
>
> 17 aug 2007 kl. 15.51 skrev Brandon Craig Rhodes:
>
> > Sebastian Ware <sebastian at urbantalk.se> writes:
> >
> >> 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.
> >
> > I agree that "How-to" generally means something much larger, and
> > involves setting up an entire product (such as the Samba HOWTO, or the
> > Linux Networking HOWTO).  I am not sure about "recipe", because often
> > a recipe is a list of instructions, without much commentary, that you
> > follow; and, at least with the tutorials I'm beginning to write, the
> > point is to explain and help you understand - they often show two or
> > three options for doing something, so that you can choose the one that
> > fits best.
> >
> > So I suppose I like "tutorial" best at this point, but you're right
> > that they are quite different from something like the Python Tutorial,
> > that shows you everything about the language in a single document.
> >
> > Would it be too "cute" to extend the caveman theme?  While cavemen did
> > leave cave paintings, calling these tutorials "Paintings" would be a
> > bit odd.  "Cave Walls" or "Cave Scratchings" also sound pretty odd.
> > The best we could probably do in the caveman direction would be to
> > call them "trails", which cave men followed through the forests.
> > ("You want to connect to a database?  Go read the ZAlchemy Trail.")
> > It would be too cartoonish to call them "Hunts", and though cave men
> > did share with each other techniques for building and honing tools
> > just like the tutorials, I can't think of a good, pithy word that
> > means "short guide to building or honing a particular kind of tool".
> >
> > --
> > 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
>