[Grok-dev] Re: grok tutorial

Martijn Faassen faassen at startifact.com
Thu Mar 8 11:41:55 EST 2007


Hey Kevin,

Thank you very much for the feedback!

Kevin Teague wrote:
> Some feedback on the Grok tutorial (now up at 
> http://grok.quintagroup.com/tutorial.html):
> 
>  * The tutorial is aimed at a very newbie developer - awesome! I spend a 
> lot of time at work assisting developers who are very new to both Python 
> and Web development in general, so it's great to have some very basic 
> docs for Grok that won't make them run away and hide :)

My target audience for the documentation is developers who know basic 
web development (web forms and such), as well as Python itself. If it 
can help developers new to both Python and web development that's even 
better of course! (Though I'll stick to the intended target audience for 
now).

As the tutorial grows, more and more advanced use cases will find its 
way into it, broadening the audience to more advanced developers. I will 
do my best to make it sound simple though, as Grok *should* be making 
things simple.

> * When ReST is converted to HTML, the sidebars are styled with "float: 
> right". I've set the headlines to "clear: both" so we don't get run-on 
> sidebars that float over other elements of the page and generally look 
> weird. However, with "float: right" the sidebar should be started *just 
> after* the headline. If they are at the bottom of the passage they are 
> floating all by themselves. I've moved them around for now in the static 
> page, but next time the HTML is regenerated they should be moved up.

Okay, I will put them just under the headline of the section, thanks for 
the tip!

>  * This is kind of a minor, picky thing, but I'm not fond of the use of 
> semicolons in the body text. Many years ago I used to do graphic design 
> for a magazine, and we had an editor who was very opposed to any forms 
> of punctuation other than the comma and the period. His point was that 
> everyone had a different idea of what a semicolon meant, and even if you 
> were dealing with folks who were educated in the forms of grammer, the 
> semicolon is a still vague creature that can't decide if it wants to be 
> a period or a comma.

I will review my use of semicolons and I'll see what I can do.

>  * The "Installing easy_install" link in the sidebar is kind of long, 
> and breaks out of the page on my browser. I could try fudging around 
> with the CSS, but it would probably read better if this:
> 
>  If you don't already have easy_install available, you can find the 
> script to set it up here:
> 
> Was rewritten as:
> 
>  If you don't already have easy_install available, you can find the 
> script on the [link to site here]PEAK EasyInstall page[end link].

I will adjust this as indicated.

>  * The tutorial page is quite large - lots of information is good, but 
> it'd be nice to break this up into several pages. I'd like to 
> configure/skin a Plone Help Center and drop that tutorial into Tutorial 
> content type object, but I'm going to do some more touching up on the 
> static site before thinking about how to tackle a dynamic Grok site.

I agree fully that this should be broken up into pages. I am assuming 
someone will write a bit of code that breaks this up (hint, hint). I 
think this should be possible with the docutils API. We could do it per 
section, but I can also look into organizing this into chapters. Let me 
know what is preferred.

>  * The tutorial is looking great so far!

Thanks! I hope to get back to writing more of it next week. It is part 
of the Grok philosophy that we should have excellent documentation. This 
also means we need great reference documentation.

Regards,

Martijn



More information about the Grok-dev mailing list