Subject: Re: FSBs and mechanized documentation
From: Jamie Lokier <jamie@shareable.org>
Date: Mon, 6 Mar 2006 18:45:52 +0000

Stephen J. Turnbull wrote:
>     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.
[...]
> My conclusion is that automatic generation by itself is not very
> useful.

I found exactly the same with many libraries.  If nobody writes
documentation, as in explanations, little tutorials, examples etc.,
then all you get from Doxygen et al is the API skeleton which is
somewhere between useless and messy, depending on the library.

For C at least, a header file is just as effective for an API
skeleton, and the source tells you what the function really does.

(I guess that's less true of other languages which don't have separate
header files - so it's handy just to have something which extracts the
interface parts from the implementation.)

However, if proper documentation is written, then I think it makes
sense to integreate it with the code in some way just to reduce
duplication, or to ensure the documentation is synchronised with the
code as much as realistically pssible.  One way to do that is to embed
the documentation in the source.  Another is to embed source in the
documentation (but that's not so popular now).  Another is to write
them both separately, and have a program verify that they agree on
factual things like arguments and types.

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

I think HTML has those threading features too (next page, previous,
up, index etc.) using the <link...> tag, but they're rarely used and
not widely supported by browsers.

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

Nice point.  "Culture of documentation".  Emacs Lisp had that too;
almost all packages came with good documentation.  Even if they didn't
have a TeXinfo manual, you could call up individual function
documentation and it tended to be a good guide, especially as you'd
usually have a natural "starting" function to look at first.

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

I find that certain structures and methods (which depend on tools)
make a big difference, though.

Writing documentation has to be a task in its own right, but if the
tools make that difficult it's not done.  If they make it easy and
rewarding, than it's more likely to be done.

I've found having a tool which converts plain text with natural "don't
have to learn anything" markup, so I can write plain text just the
same as I'd write a README file or an email, and get good looking
documents appearing immediately, to be the kind of reward which tips
the balance for me.

For me that's been a surprisingly big tip, and made a qualitative
difference to the documentation I've written (or not) for different
projects.  Not a little thing.

For others it may be the joy of hand-writing SGML or something, I'm
not sure ;)

-- Jamie