Re: [boost] Why use Boost?
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org]On Behalf Of David Maisonave "Paul Giaccone" <paulg@cinesite.co.uk> wrote in message news:<43E1D46C.7000500@cinesite.co.uk>...
There is a thread on the Boost-users mailing list at the <snip> IMHO, the help documents waist too much space in giving details that really don't help the average user to figure out how to use an interface. Take intrusive_pr document for an example: http://www.boost.org/libs/smart_ptr/intrusive_ptr.html
There's no example usage at all. It waist a lot of space giving details Synopsis and Members, but very little space for an introduction, or a good explanation on how to use it.
I agree with you on this but I'd like to take it a step further. A potential new user needs a way to find out what exactly is in boost. Right now if I want to solve a particular problem and I don't know which library to use, I basically have to drill down through the list and read the overview for each one. Even then there's no guarantee that you'll find "the right thing". Would I have found explicit cast this way? Nope. What if I want to pass messages between processes, which is the best library... I don't really know how to make it easier for a person to find just the right library but IMHO a new user considering Boost doesn't need to be "sold". They have a problem they need to solve. Once you have solved _1_ problem then that person is sold, no more marketing required. My $0.02 worth, Matt Scanned by McAfee GroupShield {X3BTB534}
IMHO, the help documents waist too much space in giving details that really don't help the average user to figure out how to use an interface.
A potential new user needs a way to find out what exactly is in boost.
I agree, the boost documentation is serves well as reference information, but is too detailed to be approachable to a new user. I would suggest something more problem-oriented, perhaps a collection of case studies that illustrate how boost can be applied to specific problems. (The Boost Cookbook?) With links back into the detailed reference material. What comes to my mind are the Graphics Gems books - collections of self-contained articles that address specific problem domains. Nigel
On Thu, Feb 02, 2006 at 08:32:30AM -0800, Matt Doyle wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org]On Behalf Of David Maisonave "Paul Giaccone" <paulg@cinesite.co.uk> wrote in message news:<43E1D46C.7000500@cinesite.co.uk>...
There is a thread on the Boost-users mailing list at the <snip> IMHO, the help documents waist too much space in giving details that really don't help the average user to figure out how to use an interface. Take intrusive_pr document for an example: http://www.boost.org/libs/smart_ptr/intrusive_ptr.html
There's no example usage at all. It waist a lot of space giving details Synopsis and Members, but very little space for an introduction, or a good explanation on how to use it.
I think it would help a lot (and would be relatively easy to establish) if every boost library documentation would have a devoted example section (I mean, real text there, not just a file), and there we would find *many simple* examples. Too often either we don't have examples, or there is one which is already quite complicated --- those are alright for later, but for the beginning we want to see simple examples, and quite a few of them. In this way one easily gets a first feeling how to use it and what to expect. Oliver P.S. A system which perfectly implements the "only-convoluted examples to show off" system is the R system; I believe that in those 5 years I'm using it (occasionally) I have never ever found any example which gave me anything; yet Boost doesn't reach that level, but with a little effort ...
"Matt Doyle" <mdoyle@a-m-c.com> writes:
A potential new user needs a way to find out what exactly is in boost. Right now if I want to solve a particular problem and I don't know which library to use, I basically have to drill down through the list and read the overview for each one.
What would you propose as a better system?
Even then there's no guarantee that you'll find "the right thing". Would I have found explicit cast this way? Nope.
Maybe because there is no boost::explicit_cast? -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
"Matt Doyle" <mdoyle@a-m-c.com> writes:
A potential new user needs a way to find out what exactly is in boost. Right now if I want to solve a particular problem and I don't know which library to use, I basically have to drill down through the list and read the overview for each one.
What would you propose as a better system?
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.) 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. 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 (with the emboldened text or something similar to catch the user's eye) Now, I know what you're thinking - come on then, walk the walk, contribute a list and we'll put it in the documentation. I would do this but I am only familiar with a handful of the libraries. If this idea is taken on, it needs to be implemented by a person who is, or group of persons who between them are, familiar with all of the libraries. Paul
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
Sebastian Redl <sebastian.redl@getdesigned.at> writes:
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.)
Now, now. Let's not discourage innovation in improving the site and docs. If Paul thinks it can be done better, he should try something and see how it works out. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Now, now. Let's not discourage innovation in improving the site and docs. If Paul thinks it can be done better, he should try something and see how it works out.
He's welcome to. I just doubt this particular idea will work. Sebastian Redl
Paul Giaccone <paulg@cinesite.co.uk> writes:
David Abrahams wrote:
"Matt Doyle" <mdoyle@a-m-c.com> writes:
A potential new user needs a way to find out what exactly is in boost. Right now if I want to solve a particular problem and I don't know which library to use, I basically have to drill down through the list and read the overview for each one.
What would you propose as a better system?
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.)
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 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
(with the emboldened text or something similar to catch the user's eye)
Now, I know what you're thinking - come on then, walk the walk, contribute a list and we'll put it in the documentation.
Brilliant!
I would do this but I am only familiar with a handful of the libraries.
So look at their introductory abstracts. It's just a few clicks from here to there.
If this idea is taken on, it needs to be implemented by a person who is, or group of persons who between them are, familiar with all of the libraries.
You could do 90% of the work and ask for corrections. -- Dave Abrahams Boost Consulting www.boost-consulting.com
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.
Beth Jacobson <bethj@bajac.com> writes:
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.
OK, care to draw up a page? If it's good maybe we'll include it with 1.34. -- Dave Abrahams Boost Consulting www.boost-consulting.com
participants (7)
-
Beth Jacobson -
David Abrahams -
Matt Doyle -
Nigel Stewart -
Oliver Kullmann -
Paul Giaccone -
Sebastian Redl