Subject: Re: Back on topic: Re: FSBs and mechanized documentation
From: Rich Morin <>
Date: Sat, 11 Mar 2006 10:02:35 -0800

At 9:37 PM +0900 3/11/06, Stephen J. Turnbull wrote:
> "Doing it really right" is equivalent to "solving AI", after all.

Yes and no.  Building a knowledge base and modeling system that can
support reasoning about complex systems can be arbitrarily difficult.
I lurk (mostly) on the Conceptual Graph and Common Logic lists, and
it's more than I can do just to get the general drift of some of the
postings.  This stuff is HARD.

Fortunately, a documentation system does not need to reason (much :)
about the target system.  It simply needs to record and exploit the
major relationships of the system being studied.  So, for example,
Doxygen doesn't need to know why one function calls another, or even
what this "means", if it can inform the user about the relationship.

Having said this, I should note that most of the existing tools are
very specialized and incomplete.  Doxygen, for example, knows about
C/C++ functions and data structures, but it doesn't look at build
information, file usage by the running program, etc.  Nor can it
handle the kinds of dynamic relationships used in Ruby, etc.

Ideally, a documentation system should be able to track any kind of
relationship that a developer might find interesting.  In rough
outline, the problem can be broken down into:

  *  Creating a model of the target system (e.g., deciding which
     entities and relationships to track).

  *  Building or finding "input filters" to harvest instance data.

  *  Presenting the results to users, in a fashion that (a) helps
     them to do their own work and (b) encourages them to submit
     comments, questions, etc.

Systems such as cover
much of this laundry list, but they wouldn't scale to documenting
the underpinnings and operation of an operating system.  However,
the basic principles are the same.

Interested parties are directed to the previously mentioned essays
on Model-based Documentation ( and my
recent blog on mechanically-augmented wikis:

--            Rich Morin     +1 650-873-7841

Technical editing and writing, programming, and web development