Subject: Re: FSBs and mechanized documentation
From: "Stephen J. Turnbull" <turnbull@sk.tsukuba.ac.jp>
Date: Mon, 06 Mar 2006 13:30:46 +0900

>>>>> "Rich" == Rich Morin <rdm@cfcl.com> writes:

    Rich>   *  The raw information is available for inspection.

    Rich>      Open Source development tools (e.g., Bugzilla, CVS)
    Rich> have accessible code and data, so tools can easily extract
    Rich> relationship information, etc.  Also, the information is
    Rich> free of proprietary restrictions.

This is generally not true of bug databases.

    Rich>   * There is a need for detailed documentation.

    Rich>      Open Source projects frequently involve large code
    Rich> bases and large numbers of geographically-dispersed
    Rich> developers.  These developers could benefit from the sort of
    Rich> web-based documentation that packages such as Doxygen
    Rich> generate.

This is unclear.  I'm not really a GTK/GNOME programmer, but I've
recently had some interest in some of the libraries they provide
(specifically related to image processing, librsvg and libgdk).  The
documentation is copious and pretty unusable---I found myself
referring to source a lot (in fact, I went and found a more usable set
of libraries, but that's a different story).  Both are due to the fact
that it's automatically generated.

My conclusion is that automatic generation by itself is not very
useful.  I also don't think that the web (ie, HTML) is a very good
medium for documentation.  As ugly as GNU's texinfo format can be, it
has a number of features that are missing from all of the HTML
documentation systems I've used (specifically, reliable forward and
backward threading across cross-references and the like).

On the other hand, I do use pydoc a lot (cd
/path/to/project/using/python; pydoc -p port_of_convenience).  Quality
varies by author, but the presence of a "culture of documentation"
combined with well-structured modules and a set of documentation
conventions that allows pydoc to generate fairly high quality
presentation means that it often does pretty well.

    Rich> I would also like to start a discussion of ways in which
    Rich> FSBs could benefit from these approaches, how projects might
    Rich> be able to collaborate on building up useful infrastructure,
    Rich> etc.

I think it comes down to a discipline of documentation, just as it
always has.


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