Subject: Re: mechanised documentation and my business model solution
From: Rich Morin <>
Date: Mon, 3 Apr 2006 10:32:11 -0800

At 11:42 PM +0900 4/3/06, Stephen J. Turnbull wrote:
> (1) Wikis are inherently page-oriented.

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

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

  b)  Wikis are a popular sub-meme in social networking.  There
      are all sorts of experimental wikis, plus things that add
      wiki features to other (e.g., CMS, weblog) systems.

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

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

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

  *  allow flexible inclusion of machine-generated content

     It isn't enough to simply let a program generate pages.  I
     also want users to be able to say "generate an X vs. Y plot
     and put it _here_".

  *  included content should be instantaneous and dynamic

     The user shouldn't have to wait until the next "build" to
     see the results.  Of course, this assumes that the needed
     data and support functions are already available.

     Content that reflects rapidly changing data should reflect
     the current values.  Generating new content on a refresh is
     a start at this.  Adding a timed refresh and/or AJAX takes
     it a bit further.

  *  allow flexible inclusion of human-generated content

     Many sets of machine-generated pages have no convenient way
     to comment, let alone edit the page content.  Documentation
     systems can benefit greatly from user feedback, but (as Ben
     noted) this must be convenient or it won't happen.

     Wikis make edits easy, immediate, etc.  Some wikis provide
     features such as discussion pages, notification services,
     etc.  These can turn random comments and page edits into a
     finely-divided forum for improving the documentation.  See
     Wikipedia for an existence proof.

  *  allow both order and chaos

     If the system is too chaotic, it will be hard to navigate.
     A perceptible and comprehensible "model" can help the user
     to know what to expect on a given page.  I like the idea of
     basing this model on the system being documented, but this
     isn't critical.  Having some order, however, is...

     If the system is too orderly, it will discourage user input.
     Even if edits are allowed, a "pristine" appearance may cause
     users to be uncertain about making changes.  Discussion pages
     help here, BTW, because users can make informal comments.

--            Rich Morin     +1 650-873-7841

Technical editing and writing, programming, and web development