[Zope3-dev] Re: Development methodology (Re: [Zope-CMF] Future CMF) (rant)

[Jim Fulton]

kapil thangavelu wrote:
> On Saturday 12 October 2002 08:29 am, you wrote:
> 
>>kapil thangavelu wrote:
>>
>>>honestly i find the information in wikis hard to get through and
>>>dissemniate, it takes alot of time to play the click tracking game, which
>>>i find distractful from the actual dissemniation of content. i would be
>>>vastly in favor of a pep style system (not proposal wise just
>>>document-wise) powered by backtalk. spend that extra time you would have
>>>spent organizing a wikis or delving through one doing something useful
>>>liking writing or coding.
>>>
>>I think the difference you're talking about has nothing to do with wiki
>>vs. PEP.  I think the difference is in the maturity level of the
>>software being discussed.  A PEP is easier to understand mainly because
>>the technology discussed (Python) is well understood.  Some of the Zope
>>3 wiki is hard to understand because the technology is still under
>>development and is not understood well enough to document.  Switching to
>>a PEP system would not change this.
>>
>>
> 
> I think i can agree to disagree :-).
> 
> Even though I don't know the C internals of python, i'm still able to follow, 
> most of the peps that discuss its internals. in contrast, the concepts in z3, 
> seem much more natural, albeit that could be because i've been to enough 
> sprints or i've had enough time to let things settle in, yet sifting through 
> the z3 wikis seems like a treasure hunt game in comparison to the peps. with 
> the peps, the fact that all the material is a single document with an easy to 
> find and read index, where i'm not forced to click through possibly several 
> links to find a new term, greatly eases the time requirements and effort for 
> understanding.  the proposal section of the z3 wikis, is actually pretty good 
> (once you know where to look ;-). but the rest of the foundational material 
> z3 wikis feels fairly hard to get hold of. the use cases for some of z3 being 
> a good case in point, imo. i dunno, maybe its a personal style preference, i 
> would rather sit on a single web page, as opposed to clicking through to find 
> new terms one per page. i'd much prefer a single structured document per 
> paradigm, with a definition section up front.
> 
> fundamentally i think it comes down to what people think the zope3 process is 
> about. if the proposal system is just a mechanism to have the community hash 
> out ideas and create content quickly, then fine, wikis are fantastic!. but if 
> the process is to create documentation artifacts, then i think its 
> problematic. put another way, why aren't the ZDG, and Zope Book in wikis. 
> Wikis are not universally liked nor do they, imo, aid in facilitation of 
> transfer of large amounts of content. they are a digital whiteboard. and 
> reading through a whiteboard as a documentation artifact is a messy business, 
> that can turn people off. take a look at the documentation  artifacts for 
> projects like php or mysql. both of them have a reputation for excellent 
> documentation on the basis of comprehensive commentable manuals (something 
> incidentally, which i think backtalk does a better job with internode comment 
> capabilities).
> 
>  wiki love isn't universal. learning how to use and read a wikis requires 
> time. ie. how do i print a wikis, how do i find this, how do i edit this, why 
> is every definition on its own page, etc. wikis are a culture, the wiki way. 
> otoh, take something like backtalk, its a straightforward intuitive natural 
> format (book/manual), with easy print (via pdf), and commenting facilities.

I think you make a good distinction. Wikis are like whiteboards. They are a
good place to contrinute because the barrier to entry is pretty low.  They aren't
so hot for documentation, at least not in their current state.  You are also
right about differing tasts. The freedom and openness that wikis provide are
work *a lot* to me. So much so that I'm willing to put up with a lot of
shortcomings. I understand that other people feel different.

After the first alpha release, which I want to get out before the end ofr 2002,
I'd like to put som eearnest effort into creating a zope3.org site. I think that
would be a good time to look at different documentation tools, whether they be
like improved wikis, backtalk, or some sort of fusion. (For example, I'd like to
create views on Wiki sites that collect many wiki pages into one web document that
can be more easily read, printed, etc.) Perhaps some folks should put some effort
into talking about what they want for zope3.org.  Would enybody be willing to lead
a zope3.org design effort?

In the mean time, I hope we can be mature enough and do the best we can with the tools
at hand. I think it would be too disruptive to reinvent the process prior to the alpha.

Jim

-- 
Jim Fulton           mailto:jim@zope.com       Python Powered!
CTO                  (888) 344-4332            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org