Subject: Re: mechanised documentation and my business model solution
From: "Ben Tilly" <btilly@gmail.com>
Date: Thu, 6 Apr 2006 20:56:41 -0800

 Thu, 6 Apr 2006 20:56:41 -0800
Sorry to reply so late, I've been on vacation.

Here is my modest proposal.  The ideal system is an extensible wiki
with an extensible markup language allowing the easy insertion of a
variety of types of autogenerated information.  (Wikis already do
this, allowing autogenerated indexes and the like.  You just want to
add lots more stuff.)  Add plugins to autogenerate the various kinds
of information that you are interested in, and the ability to
autogenerate lots of stubs  based on what is in a repository, and
you've got a pretty good and flexible tool.

On 4/3/06, Rich Morin <rdm@cfcl.com> wrote:
> 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.

And human constraints make this natural.  However nothing stops you
from having a wiki that is backed by a source control system. 
Furthermore if you add a conflict resolution system, then the
web-based interface could update only the wiki part of the project,
but the wiki could be part of the actual source tree that programmers
work with. This allows programmers to synchronize documentation
checkins with the associated code, yet lets external users make their
own comments.

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

You need to draw the line between what is done mechanically and what
is done by humans.  I think the version that I suggested draws that
line in a fairly natural place.

>   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.

Wikis hit an interesting usability sweet spot.

> > ... 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.

In general the more control you add, the more difficult it becomes to
administer and use the wiki.  Provide the option of control, but
default it to being simple.

> > 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".

Sorry, I have a marginally informed bias against Zope.

The most competent person who I personally know who has used Zope in
anger, found that it was great for the initial prototype and then
sucked badly from then on.  That was Zope 2.3 though, so lots of stuff
may be better, but the initial bad impression sticks.

I also don't like repository-based systems.  There are a lot of
filesystem tools, and you're either asking people to throw them away,
or else to build new ones and develop a lot of specific expertise to
use your system.  Unless there is a very big win from doing so, it
isn't worthwhile.

> 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 ".

My proposal does this.

>   *  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.

Depends on how the plugins work.  Leaving the option of making some
data slower to refresh is an important system optimization in some
circumstances.

>      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.

Doable with my suggested approach.  (You autogenerate certain kinds of
data by including a tag and some JavaScript that populates then
refreshes the contents of that flag.)

>   *  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.

My proposal does that.

>      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...

I think my suggestion does this.

>      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.

That's the beauty of autogenerated stubs.  It is obvious that there is
something there, and it is obvious what needs to be done to improve
it.

Oh, and if the wiki is backed by a source control system as I
suggested, then we add my top desire - the documentation can easily
ship with the source code. :-)

Cheers,
Ben