11 April 2008 2 comments Zope
Martijn Faasen is my hero. Not only is an absolutely brilliant coder he's also able talk so that mortals understand.
What he's replying about is mainly the question "What does Grok give me that, say, django does not?"
And, this is why I dislike Grok
Yes, you clever people. It's the same link. For some reason all the great documentation goes into replies on the mailing list rather than into a concise web page with cookbook, book and styled and funny tutorials. Why is that? They've actually made it quite easy now to enter documentation on grok.zope.org with the new Plone site.
An equally important question is: Why don't I do something about it rather than to complain? Well, I've written one how-to at least. My other "excuse" is that I'm not yet an expert enough and hence writing good documentation takes a very long time.
I think there's an important philosophical and political issue at hand. The Grok community is filled with really clever people who are very senior in the web development industry who like using mailing lists and perhaps more importantly, don't need documentation since they can study source code and unit tests to answer their questions. I know this is a sensitive statement but I'll take my chances since it implies that these guys are smarter (or perhaps just more time on their hands).
My internal battle of which new web framework to put my energy into continues. Today (thanks to Martijn's post) Grok earned one more point.
One of the problems with complex and somewhat magical systems is that newer developers lack the confidence to document the system, even when they might actually have all the necessary knowledge. To document something you have to know how to do something, *and* you have to have a certain amount of confidence that you know it right.
I just found this entry; wow, I don't think I've been anyone's hero before. :)
Ian: that's true for just about any piece of software. For Grok we actually are seeing quite a few documents that people have contributed over time, something I'm pretty happy about.
I need to edit that mailing list message to an article for grok.zope.org, indeed.