Subject: Re: Back on topic: Re: FSBs and mechanized documentation
From: "Stephen J. Turnbull" <turnbull@sk.tsukuba.ac.jp>
Date: Sat, 11 Mar 2006 16:59:18 +0900

>>>>> "Forrest" == Forrest J Cavalier, <mibsoft@mibsoftware.com> writes:

    Forrest> Rich Morin wrote, in part....

    >> Nonetheless, I haven't found much evidence of these [automatic
    >> documentation] tools being used in the Open Source community.

    Forrest> Lacking evidence of existence of something "needed", I'd
    Forrest> say there is an incorrect assumption somewhere.

Are you implying that "maybe" they're "not needed" because such usage
doesn't exist?

Economics doesn't allow you to draw such a conclusion; there may very
well be a "market failure" somewhere.

I think that's the explanation.  Most open source software projects
(by _count_, not by something more correlated with economic impact)
are based on a programmer or a "tight" group of programmers scratching
an itch.  They know what they want the widget to do, they make it do
that, they wrote the internals, who needs documentation?

_Clients_, that's who.  (By "client" I mean both "paying customers"
and "client software", ie, modules that call yours.)  But you can't
get them to pay for the documentation any more than you can get them
to pay for program.  It was claimed that the BookInTheBox was why
people would pay $75 for a genuine copy of Red Hat Linux even though
CheapBytes was selling CDs for $2.95.  Well, Red Hat is out of that
business, now.

Thus is the "the business is the documentation" business model born,
aka "software is a loss leader, make it up on the consulting" model.

Grossly Networked (Overly so) Massive Environments.  To be a little
objective about it, I'm a GNOME outsider, always will be, I think.  I
try to use a couple of GNOME libraries, and suddenly GNOME takes over,
and I don't understand it, so it becomes another GNOME app, not what
*I* wanted.  But that's the *good* thing about GNOME, right?  Users
know how to use it, because the UI is a library that all programs use.
GNOME programmers know how to interconnect stuff, because they use it
all the time.  Note that if you're going to use GNOME a lot, the
effort is *very* well repaid.  So, who needs documentation?  Me, but
the world doesn't revolve around me.  (Thank heaven!)

X11, for all its flaws, is quite well-documented ... up to about
X11R5.  All the new stuff ... XKB, XOM, XIM, IIIMF, Xft, fontconfig,
XRender, XDarwin, to list the ones I've looked at closely enough to
have an opinion ... hey, you've got the source, Luke!  Now,
kwitcherbitchin!  Is it a coincidence that the release of X11R6 was
about the time that XFree86 started to pick up steam, and quickly
became an acknowledged leader in X11 development?

So, OK, there you have me talking out of both sides of my mouth.  On
the one side, I'm arguing that living in GNOME means you don't need to
document (or that auto-docs are sufficient), since most of those who
care live in GNOME, too.  On the other, I'm pointing to circumstantial
evidence that a revenue-generating enterprise (here, indirectly based
on selling proprietary software) can afford to produce documentation
and will do so.  (Yes, that's very loose, but I don't have time to
make it precise today.  Feel free to knock holes in it, but try to
make them big ones, not just little moth bites.)

-- 
Graduate School of Systems and Information Engineering   University of Tsukuba
http://turnbull.sk.tsukuba.ac.jp/        Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
        Economics of Information Communication and Computation Systems
          Experimental Economics, Microeconomic Theory, Game Theory