Paul Giaccone wrote:
The issue is this: the current documents say "Library X does Y", or, in functional notation, y = foo(x). If you know x, you can find y. Unfortunately, the new user knows y, and so needs x = bar(y), where bar() is the inverse of foo(). (What's more, the user doesn't even know that they need x = bar(y) because they don't know that Boost deals with y by providing bar(y) until they start hunting through the docs.)
The problem is that foo(x) returns multiple values, thus there are more bar(y) functions for each x than is practical to list. In other words, x and y are not isomorphic. To get away from the analogy, what I'm saying is that since there is no standardized description for each problem that each user comes up with intuitively, a user searching for specific functionality can take no shortcuts - he'll still have to search through the short description of each library, for which the alphabetic library list is adequate, and the categorized listing even more so. (The descriptions could be made a bit longer, perhaps. Perhaps.) Sebastian Redl