[Zope] Re: Is Structured Text Broken in Zope 2.4x ???

[Chris McDonough]

Hi Simon,

> But seriously, why you feel this is a wiki problem ?  Did you mean
> "the way we are currently using wiki for zope documentation" or wiki
> technology in general ?


The former, mostly, I think. Wikis are not really the best tool in
their current forms for this goal because they heavily encourage
"bazaar"-style collaborations that are somewhat at odds IMHO with
documentation's humdrum purpose, which is to boil complicated stuff
down to explicable chunks). The bazaar loves complexity, documentation
loves simplicity.

People read documentation *way* more than they write it, even more so
than code; they want to read it and maybe suggest corrections, but in
the end they want some accountability for what they're reading.  They
want to know that some version of what they're reading is "canonical".
They also want its ordering to be maintained and for it to be
consistent.   Documentation in this respect is more "cathedral" than
"bazaar", if only because it attracts fewer people because there's not
much glory in keeping it up.  Still, it's useful to lower the bar as
much as possible for people to contribute to documentation artifacts
when there's a mistake or a hole.

This is one of the reasons I helped write BackTalk, which runs the
Zope Developer's Guide on Zope.org.  It's wikilike in that it lets
community folks contribute to docs, but in a limited and clearly
additive fashion that leaves little question to what is canonical and
what isn't.

- C