Subject: Re: mechanised documentation and my business model solution
From: Rich Morin <>
Date: Tue, 4 Apr 2006 01:04:45 -0800

At 3:34 PM +0900 4/4/06, Stephen J. Turnbull wrote:
> Sure, but documentation is of the human, for the human,
> by the human.

Actually, I only accept the middle assertion.  Documentation
of a system may well document things that were never even
considered by its "designers" (e.g., emergent phenomena).  I
can also show you many systems where useful information is
harvested, formatted, and presented by programs.  That said,
the human element is absolutely critical...

> Human authors using a wiki will be page-oriented unless you
> provide features that encourage them to work otherwise.

I expect humans to be page oriented, in large part because it's
so difficult to manually edit multiple pages in a consistent
and cohesive manner.  However, the underlying structure may be
laid down by the mechanized documentation system.

Taking your Python example, what if the output of Epydoc or
Synopsis were poured into machine-generated pages in a wiki?
They would have the same information content, but they would
now support comments and questions, as well as additional
pages that some user thought might be interesting.  So, the
wiki begins with a consistent, machine-generated framework,
but add-ons are not limited by this structure.

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

Sorry, you lost me...

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

I'm not saying that Zope wouldn't work.  I'm just not familiar with it,
so I tend to discuss technologies (eg, MediaWiki) I'm currently using.

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

Again using MediaWiki as an example, there's quite a bit of code that
supports the ability for users to create links, do mark-up, include
text from other pages, etc.  Making this easy for the user is really
important to the developers, to the extent that useful-sounding mods
may get dropped if they look too complicated to use, explain, etc.
I support this orientation for the Wikipedia case, but I might allow
fancier mark-up in another environment.  One size does not fit all...

> LFTD (looking forward to delivery). :-)

Me too!  However, as long as I'm doing it as a self-funded effort, my
progress may be slower than either of us might wish.  In any case, my
efforts are aimed at fulfilling ESR's notion of a "plausible promise":

> When you start community-building, what you need to be able to
> present is a plausible promise.  It can be crude, buggy, incomplete,
> and poorly documented.  What it must not fail to do is (a) run, and
> (b) convince potential co-developers that it can be evolved into
> something really neat in the foreseeable future.

  Necessary Preconditions for the Bazaar Style
  The Cathedral and the Bazaar

Eric doesn't mention sponsors, but this is obviously another way to
move things along.  If some largish Open Source project wants this
sort of technology, they know where to find me :-).

FWIW, my active development has only recently begun on the current
instantiation of these ideas.  Having chosen MediaWiki as a starting
point, I've written a couple of small scripts (using pywikipediabot)
to get and put pages.  I'm now working on a naive set of entity and
relationship class definitions for the sorts of things that are
externally visible in Unix systems: files, processes, signals, etc.

Once I get this loaded into the wiki, I'll ask for critiques by folks
who understand Unix and/or knowledge engineering, then start looking
at filling in lower-level definitions and instances, using some of the
techniques I used for the FreeBSD Browser.  My goals and approach are
laid out in

--            Rich Morin     +1 650-873-7841

Technical editing and writing, programming, and web development