| We do work constantly on documentation. However, most of this effort
| has gone into improvements to the man pages and such.

Part of the problem here is that whenever there are multiple documentation
sources for a given fact, they have the opportunity to get out of sync.

At the present time, I think developers do a reasonably good job of
keeping manpages in sync with reality. This happens because there is
a cultural requirement to do so, and it's relatively easy. Manpages live
with packages they document (well, in many cases), and it's relatively
obvious that a manpage should be updated when the code is changed.

This is hardly the case for lots of "extraneous" documentation out there,
be they URM/USD/etc. or web pages or FAQs, etc.

I don't know what the solution is.

In my corner of the world, I try to pretend the solution is not to have
those other sorts of documentation, however that's not realistic and
is perhaps not even fair.

The two solutions (both of which suck) that come to mind are:

1)  Making sure there's a listing of references to a module of the codebase
somewhere, so when that module is changed, it's easy to know what other
pieces of documentation has to be updated.

2)  Have a Unified source for all the documentation. Conditional compiliation
of human-readable documents is an annoying problem, and it tends to be
hard to maintain.

But I think it's important to recognize what the problem is before we
try too hard to solve it.

--jhawk