[Grok-dev] Role of the Grok Wiki

Martijn Faassen faassen at startifact.com
Fri Dec 18 11:35:45 EST 2009


Hey,

Kent Tenney wrote:
> I have proposed what strikes me as a compromise: add links
> to an editable wiki page, where namespace owners, project owners,
> and busy bodies like me could put additional information.

That sounds like a good idea.

> =====================================
>  Grok Wiki
> 
> The Grok Wiki on zope.org. Use this for temporary throw-away documents
> about Grok,
> sprint planning, and so on. More permanent documents about Grok should
> be part of
> this website - please contribute!
> =====================================
> 
> I think that sells the Wiki concept short, and fails to take advantage
> of the years of work Simon Michael has put into Zwiki.

Let me explain the motivation behind this. The Zope community has had 
years of experience with wikis. In my experience it turned out to be 
very difficult to keep many wikis maintained and navigable. I often 
ended up rather lost in a forest of wiki pages. This applies especially 
to the Zope 3 wiki, and also to the "how to become a contributor" wiki 
page which I could for some reason only find after a struggle to 
remember, over and over again each time I needed it.

In the Grok community I therefore strongly encourage a more structured 
approach to documentation, where there's a documentation artifact (the 
website, docs in SVN) that we care actively about.

I realize that of course wikis *can* be successful and successfully 
maintained (wikipedia is a great success story), but I also think that 
the current Grok site works a lot better than some of the Zope-related 
wikis I've seen.

I don't think this conflicts with your notion of having a wiki "talk" 
page per library we discuss on the library page, where people can very 
easily contribute more information. I'd see such a talk page as a 
temporary throwaway area with useful information, questions and 
comments, that hopefully occasionally people will fold into either the 
official documentation for the package discussed, or the Grok 
documentation on the grok web site.

> Returning to the intro to the Grok Wiki, it was unclear to me what the request
> 'please contribute' means, so, via 'Documentation' -> 'Contribute' I reach
> a page which describes a somewhat formal process for contribution.

I'm not sure I understand. Do you have a suggestion as to how we can fix 
the text?

> I think the wiki could fill a gap between the temporal stream of information
> the mailing list provides, and the submitted, reviewed and published howtos
> and tutorials the documentation site offers.

I agree. I think that fits the description of the wiki, but..

> It seems that changing the description of the wiki,

what would you suggest as an improved description? I'm sure it can be 
improved, but I don't want to lose the original meaning that we really 
don't want the wiki to be a permanent location for organized 
information, but move this to more formal documentation.

> and maybe adjusting
> permissions (I was unable to create a page) would be sufficient to provide
> a convenient entry point for submitted information.

As to permissions to create a page, could I delegate you to look into that?

> With a little promotion, the wiki might become valuable, at no appreciable
> cost to the formal documentation team.

+1. I think the best way to discuss this is to offer "extra info" wiki 
links per package and link them in. We can then see how that works, and 
perhaps offer such links to wiki pages elsewhere on grok.zope.org as well.

Regards,

Martijn




More information about the Grok-dev mailing list