[Grok-dev] Re: Mini tutorials

[Sebastian Ware]

If we could just keep them short and not broken... it kind of makes  
it easier for a newbie (i.e. me...) not having to understand  
everything at once... :)

In my experience, people tend not to maintain long and extensive  
documents.

Mvh Sebastian

5 jul 2007 kl. 15.52 skrev Martijn Faassen:

> Sebastian Ware wrote:
>> Humbly... I suggest the following guidelines when writing mini  
>> tutorials.
>> A mini tutorial is a primer to get a newbie started with a  
>> component or a pattern.
>> -Keep them short (5-10 min read)
>> -Include working code samples
>> -Focus on a single component/pattern
>> -Only explain the basics, but still making it useful immediately
>> -Give reference to further reading
>> These mini tutorials could turn into a repository of patterns and  
>> practices. I would personally have saved A LOT of time if I had  
>> had such examples. I think many newbies like to copy and tweak  
>> existing code. It would also reduce the support effort for the  
>> community since it narrows the errors newbies make.
>
> It's good to have some guidelines for tutorials, so thank you for  
> them.
>
> I'd like to add to this though. The general guideline should be: if  
> you want to write a tutorial or howto, please do! If they're too  
> long, too short, broken, badly written, they're still better than  
> *no* tutorials, and we can always clean up later.
>
> The people working on the "proper" tutorial can go through the mini  
> tutorials and integrate interesting material over time, too,  
> cleaning it up in the process.
>
> Regards,
>
> Martijn
>
> _______________________________________________
> Grok-dev mailing list
> Grok-dev at zope.org
> http://mail.zope.org/mailman/listinfo/grok-dev