Subject: Re: mechanised documentation and my business model solution
From: "Stephen J. Turnbull" <turnbull@sk.tsukuba.ac.jp>
Date: Tue, 04 Apr 2006 15:34:21 +0900

>>>>> "Rich" == Rich Morin <rdm@cfcl.com> writes:

    Rich> At 11:42 PM +0900 4/3/06, Stephen J. Turnbull wrote:

    >> (1) Wikis are inherently page-oriented.

    Rich> I think this is true for (a) interactive use of (b) wikis
    Rich> that I know about.

    Rich>   a) Mechanical augmentation may generate arbitrary numbers
    Rich> of pages, providing "version sets", indexes, high levels of
    Rich> consistency and cross-page linking, etc.

Sure, but documentation is of the human, for the human, by the human.
Human authors using a wiki will be page-oriented unless you provide
features that encourage them to work otherwise.

There was a thread on this on python-dev a couple months ago, where
they are wrestling with the documentation of the burgeoning set of
standard and semi-standard libraries distributed with Python.

    Rich>   b)  Wikis are a popular sub-meme

"Sub-meme"? :-)

    >> ... WikiWikiWeb achieves this goal radically---by removing
    >> *all* discipline.

    Rich> Although many wikis are wide open, many are not.  For
    Rich> example, Wikipedia is wrestling with this very issue, trying
    Rich> to achieve a balance that keeps a high signal-to-noise
    Rich> ratio.  My take is that it is quite reasonable for a wiki
    Rich> administrator to set and enforce read and/or write access.

That's not the domain of discipline I'm talking about.  I'm talking
about discipline of those with write access.

    >> Really, given the variety of disciplines that various people
    >> have described in this thread along, a much more appropriate
    >> way to describe what we need is "Zope/CMF" or "Plone".

    Rich> Perhaps.  Rather than specifying the answer, however, we
    Rich> should be looking at the question.  What specific features
    Rich> do we want?  Here's my own (admittedly incomplete) wish
    Rich> list:

    Rich>   * allow flexible inclusion of machine-generated content
    Rich>   * included content should be instantaneous and dynamic
    Rich>   * allow flexible inclusion of human-generated content
    Rich>   * allow both order and chaos

Still looks like "Zope" to me!  Now, where did I put that thumbnail?

Less facetiously, there's a meme in Zope's online documentation "Why
can't I create my Zope site through the web (TTW) any more?"  TTW
specifically refers to low-level stuff that used to be done with
Python scripts that called a certain set of Zope APIs.  You could edit
these in your web browser.  This feature has gradually been deprecated
in favor of "ssh to the Zope host and add Python modules to the Zope
library like a Real Programmer".

One way to look at this is "oh, well, no matter what we do, we're
going to end up with a Turing-complete documentation system".  I'm not
so pessimistic, but I suggest that your system should focus on making
those things that it can do somewhat complete, moderately
good-looking, but *really* easy to use.  Or people will prefer to use
more powerful tools, directly, to get better results without all that
much additional pain.

I use wikis a lot, for various purposes, most of them not even
collaborative.  That's because they do most of what I want, it's much
harder to produce an ugly wiki page than an ugly MS Word document :-),
plain-ish text source is easy to analyze, and they're drop-dead easy
to use.  I think your doc system should aim at the same balance of
features.  FWIW, YMMV, LFTD (looking forward to delivery). :-)

-- 
Graduate School of Systems and Information Engineering   University of Tsukuba
http://turnbull.sk.tsukuba.ac.jp/        Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
        Economics of Information Communication and Computation Systems
          Experimental Economics, Microeconomic Theory, Game Theory