Subject: Re: FSBs and mechanized documentation
From: simo <>
Date: Sat, 11 Mar 2006 18:22:26 -0500

On Sat, 2006-03-11 at 13:42 -0800, Rich Morin wrote:

> True, though we tolerate quite a bit of noise in, say, the
> results that Google provides.  If the first page has two
> hits, six plausible matches, and 40 misses, I'm happy.  If
> you're looking for all of the bug reports that involve the
> foo() and bar() functions, and the doc system can report
> them in a second, it can save you a lot of time and effort.
> My focus on entities and relationships, however, is not an
> accident.  If a human has declared that particular types
> of entities can have particular types of relationships, and
> the instances of relationships can be filled in by humans
> or programs, the results are likely to be highly reliable
> and very specific.
> Of course, most of the relationships will be irrelevant to
> the question at hand, even if they concern an item that the
> user has specified.  A function may make dozens of function
> calls and be called by hundreds of other functions.  It uses
> specific data structures, is mentioned in certain documents,
> and resides in a file which uses certain include files, etc.
> Giving the user a way to winnow out "noise" relationships
> isn't trivial, but there are some useful principles that can
> be applied.  For example, we know that humans are much better
> at pattern recognition and selection than they are at
> specifying and remembering details.  So, we let the machine
> present possible matches (and match criteria).  The human can
> then navigate to the ones that seem most promising.
> Again, I seem to have drifted off into design questions, but
> I hope that this convinces you that the object isn't just to
> collect and present random data.

I see your point, I must say I mostly agree with you, in fact when I
approach a new project source code, I tend to use Source Navigator,
because it features a very good, and easy to use relationship database
that let you easily navigate the code by following functions and
inspecting structures. When I am accustomed to the code, I tend to go
back to vim + cscope as I generally know what functions or which
relationship I'm looking for, so that the editor features become more
important than the fact that Source Navigator relationship database is
easier to use than the one of cscope.

By analogy, I think that it would probably be true for bugs databases
relationship tools as well, but I think that the tool is going to be a
powerful thing only if very easy to use so that it let you easily
exploit these relationships without making you lost in the maze. Other
wise just browsing the db by the usual included search engine will be