David Abrahams wrote:
Paul Giaccone <paulg@cinesite.co.uk> writes:
A better system would be (in addition to what is already there, rather than as a replacement for it) to provide this inverse function in the docs, so, in addition to the alphabetical list at http://boost.org/libs/libraries.htm (which is foo()) there is a list corresponding to bar(), but with a little more detail.
That's what http://www.boost.org/libs/libraries.htm#Category is all about.
I would keep that, but also have a page that categorizes the libraries according to their appropriateness for different types of users, e.g. "C++ Tweaks" for people who don't really need anything special, but just want to make programming a little easier (this would include things like smart pointers, boost arrays, static asserts, etc), "General Use Libraries" for people who want better written, wider featured, or cross platform versions of commonly used libraries like date-time, threading, etc., "Specialized Libraries" like BGL, uBLAS, maybe the Python interface, etc., "Bleeding Edge Programming," for folks whose main interest in Boost is in gaining experience with the most up-to-date techniques such as the meta-programming stuff.
I am thinking of something along the lines of:
Standard C++: *Memory allocation on the heap*, which requires careful management by the user Boost: *Smart pointers*, which do not require this kind of management
I like this a lot. I wonder if it would also be appropriate to do a similar comparison between popular third-party libraries and the boost versions. For example, we chose the Boost date-time library over Microsoft's because it has fractional seconds. I think the Boost version is far superior anyway, but I wouldn't have been able to justify using a non-standard (for VC programmers) library without that specific advantage. I first came across boost when I was looking for libraries to use for a new project. Googling turned up a class of libraries that I thought might perhaps possibly fit, but despite the extensive online documentation of various versions, I couldn't tell whether it was right for us or not. Then I came across the boost version, and thanks to the "Rationale" section, was able to determine almost immediately that it was NOT what I wanted. I had no reason to think any of the other boost libraries would help either but using "look for your keys under the streetlight" logic, I figured they were worth looking into, and as it turned out, I found a few that were appropriate to our needs. There are a couple of morals to this story. First, a Library Rationale section should be required for every library. Some may include a Design Rationale section too, but the library rationale, explaining what need the library fills, is a huge timesaver and a great way of encouraging people to browse the libraries. Second, while the high quality of design and programming, review process, etc, are great selling points, I (and I suspect the majority of users), would never get that far if we didn't first come across a library that filled a specific need. Rather than finding copywriters to tell everyone that boost is the Greatest Thing Ever, I think the key to selling the libraries is to first hook the user with a feature that justifies the time required to evaluate boost. In other words, Paul is definitely on the right track.