Re: [boost] Why use Boost?

From: David Maisonave (dmaisonave_at_[hidden])
Date: 2006-02-02 10:18:28

"Paul Giaccone" <paulg_at_[hidden]> wrote in message
news:<43E1D46C.7000500_at_[hidden]>...
> There is a thread on the Boost-users mailing list at the moment asking
> what users needed to know when they got started with Boost.
> 
> One of the points raised is that, while pretty much all users of Boost
> think it is great, they didn't know when they started using it why it 
> was so great and why it would be to their advantage to use it.  One of

> the reasons for this is that the front page of the website does not 
> really sell the product.
> 
> I agreed with this point.  Here's a summary of my posting:
> 
> "What the site needs, in my view, on the front page is some sort of
> material selling Boost. Why was Boost set up in the first place?  

I totally agree 100%.

IMHO, for the most part, the site is setup as if users already know
about boost.
Most of the help documents seem to be targeted for more advanced C++
programmer.
They make no real attempt to sell the library.

Although I knew about boost for a long time, I didn't start using it
until recently, because I was under the impression, that I would need to
add additional *.cpp or lib files to my project in order to use boost.

I also thought my binary would increase substantially if I linked to
boost just to use a specific object like boost::shared_ptr.

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.
As a user, why would I care about the Synopsis or Members, if I can't
figure out how to use the interface.
There should be more focus on introduction and example usage, and less
focus on Synopsis and Members section.
Moreover, IMHO, in Members section, each member should have an example
usage.

Take a look at weak_ptr
http://www.boost.org/libs/smart_ptr/weak_ptr.htm
Look at the members section for lock and rest.
There's no usage example and no explanation of their purpose.  Why would
I care that it throws nothing, if I don't know what it's for.

I think there would be 10 times more boost users, if the boost
developers put the same quality into the documents, as they do into the
code.
It would also help developers, if boost had a really GOOD template to do
this, and it would serve as a check list for required/recommended
documentation.

What's the point of creating a great class, if only a handfull of
developers ues it, because the majority have no idea how to use it?