Subject: Re: business case for mechanized documentation
From: Rich Morin <>
Date: Mon, 10 Apr 2006 10:26:49 -0800

At 9:22 AM -0700 4/10/06, Thomas Lord wrote:
> I've only lightly followed the technical discussion about the
> project and (perhaps because of that) have trouble seeing the
> critical differences between Rich's thing and lots of other
> existing and potential tools.  I don't see any compelling
> reason to believe that *his* approach is going to make a big
> difference compared to efforts already underway (and in some
> cases, essentially done).

There are several issues that we could discuss.  Going down one
path (from the abstract to the particular), we might ask:

  *  Does mechanized documentation, in general, have anything
     to offer the Open Source vendors and community?

  *  What are the good and bad points of the existing tools?

  *  What direction(s) should development take?

  *  Are Rich's ideas, in particular, worth pursuing?

Although I'm quite willing to discuss any of these, only the
first is "on topic" for the FSB list.  So, let's hypothesize
that a combination of new and existing tools could be used to
generate detailed documentation for Open Source projects, with
relatively little effort (at least, initially) by the coders.

Given this assumption, let's look at the business case.  What
benefits would such a facility provide for a vendor such as IBM,
Novell, Red Hat, Sun, etc?  Are there any drawbacks to having
such a facility available?  What are the major costs of putting
the facility up and maintaining it?

Some of these questions have already been brought up, but have
not been discussed in any detail.  Let's see if any of them are
worth pursuing...

  *  benefits

     *  In a battle for "mind share", a vendor may benefit from
        having an accessible and comprehensible code base.  In
        fact, even the _appearance_ of these aspects is helpful,
        in that prospective adopters and/or developers may be
        induced to participate.

     *  By developing and deploying infrastructure, companies
        can create "support" markets for themselves.  The UIMA
        effort by IBM looks like an effort in this direction.

     *  Infrastructure that helps developers to understand what
        is going on inside the software may improve engineers'
        productivity.  This looks like the motivation for Sun's
        development and deployment of DTrace.

  *  costs

     *  Even if an all-singing, all-dancing documentation system
        were already available, deploying it on a substantial
        code base is non-trivial.  Add to this the hardware and
        maintenance cost of adding web servers, databases, etc.

     *  Although a mechanized system can harvest and present data
        about the entities and relationships in a system, it can't
        generate explanations of their purposes.  Filling in this
        information requires human time and effort.  Even if most
        of the work is done by volunteers, the vendor may have to
        fund some coordination, etc.

  *  drawbacks

     *  There may be a case for having a large, inscrutable code
        base which is still technically "Open Source".  We've all
        heard the half-joking assertion that this or that project
        supports itself by making their incomprehensible software
        work.  If a vendor doesn't WANT their code to be accessible
        and comprehensible, a mechanized documentation system would
        not be in their best interests.

Feel free to take on any of these points, add your own, etc.  The
object here is to see if a reasonable business case can be made.

--            Rich Morin     +1 650-873-7841

Technical editing and writing, programming, and web development