Why use Boost?

classic Classic list List threaded Threaded
59 messages Options
123
Reply | Threaded
Open this post in threaded view
|

Why use Boost?

Paul Giaccone
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?  
Because, in some areas, C++ is deficient, is difficult to use or expects
too much of the programmer. Boost helps by providing what is useful but
missing and takes a lot of the work out of C++ programming.

"Essentially, Boost needs to sell itself as something that no C++
programmer would want to be without. Think how the adman would write it:
"C++ getting you down? Spending hours tracking down that memory leak?
Then try Boost! It will change your life!" Well, maybe not, but
something along these lines would certainly go a long way to showing why
anyone should be using Boost. At the moment, the front page tells me is
that the libraries are free, portable, peer-reviewed and work well with
the C++ standard library, but that doesn't tell me why it is to anyone's
advantage to use them."

David Abrahams of Boost Consulting, who started the thread, suggested
that I write a paragraph for a selection of Boost libraries that did
just this.

Below is what I came up with, from my experience as a Boost user who has
used the libraries mentioned.  I think it would be helpful to both users
and developers if this text or something similar could be included on
the front page of boost.org or some other prominent place on the
website.  For myself, if I had seen something like this content on the
front page, I would have rushed to download the libraries.  What do you,
as the developers, think of this proposal?

Keep up the excellent work.

Paul Giaccone

"Memory allocation on the heap in C++ requires the programmer to manage
the memory, make sure that there is always at least one pointer to the
memory and deallocating it at the right time.  It is easy to forget to
do this or to do it in the wrong place in the code, which causes memory
leaks, or, worse, program crashes.  Boost makes life easier for the
programmer by providing various 'smart pointers' that automatically
maintain memory allocated on the heap, deallocating it at the right time
and requiring minimal intervention from the user."

"A programmer wanting to read and write structured data (such as the
member variables of a class) to file can run into a number of problems.  
How should the data be formatted when written to file?  Do the read and
write functions correspond exactly?  If the structure of the data
changes in future releases of the program, will it still possible to
read files that were written using the old format?  Are files written on
one platform readable on another?  How should pointers be handled?  
Boost provides a serialization library that manages all of these
problems and more simply and elegantly."

"In standard C++, handling multiple command-line arguments usually
requires the user to write a bespoke parser to read in and interpret
these arguments and handle syntax errors, missing arguments, duplicated
flags and the like.  Boost's program_options library handles
command-line arguments without fuss."

"Writing user-defined input and output streams can be tricky.  The Boost
iostreams library gives the user easy access a range of useful
functionality, including data encryption, compression in various
standard formats, line-ending conversion and output in XML format."

"C++ allows for casting between similar types, such as int and double.
The Boost conversion library extends what is possible with casting,
enabling the user to cast integers to strings and vice versa, and to
cast safely between polymorphic types."


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

Edward Diener
Paul Giaccone wrote:

> 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?  
> Because, in some areas, C++ is deficient, is difficult to use or expects
> too much of the programmer. Boost helps by providing what is useful but
> missing and takes a lot of the work out of C++ programming.
>
> "Essentially, Boost needs to sell itself as something that no C++
> programmer would want to be without. Think how the adman would write it:
> "C++ getting you down? Spending hours tracking down that memory leak?
> Then try Boost! It will change your life!" Well, maybe not, but
> something along these lines would certainly go a long way to showing why
> anyone should be using Boost. At the moment, the front page tells me is
> that the libraries are free, portable, peer-reviewed and work well with
> the C++ standard library, but that doesn't tell me why it is to anyone's
> advantage to use them."
>
> David Abrahams of Boost Consulting, who started the thread, suggested
> that I write a paragraph for a selection of Boost libraries that did
> just this.
>
> Below is what I came up with, from my experience as a Boost user who has
> used the libraries mentioned.  I think it would be helpful to both users
> and developers if this text or something similar could be included on
> the front page of boost.org or some other prominent place on the
> website.  For myself, if I had seen something like this content on the
> front page, I would have rushed to download the libraries.  What do you,
> as the developers, think of this proposal?
>
> Keep up the excellent work.
>
> Paul Giaccone
>
> "Memory allocation on the heap in C++ requires the programmer to manage
> the memory, make sure that there is always at least one pointer to the
> memory and deallocating

deallocate

> it at the right time.  It is easy to forget to
> do this or to do it in the wrong place in the code, which causes memory
> leaks, or, worse, program crashes.  Boost makes life easier for the
> programmer by providing various 'smart pointers' that automatically
> maintain memory allocated on the heap, deallocating it at the right time
> and requiring minimal intervention from the user."
>
> "A programmer wanting to read and write structured data (such as the
> member variables of a class) to file can run into a number of problems.  
> How should the data be formatted when written to file?  Do the read and
> write functions correspond exactly?  If the structure of the data
> changes in future releases of the program, will it still possible to
> read files that were written using the old format?  Are files written on
> one platform readable on another?  How should pointers be handled?  
> Boost provides a serialization library that manages all of these
> problems and more simply and elegantly."

,and more,

>
> "In standard C++, handling multiple command-line arguments usually
> requires the user to write a bespoke

bespoke ?

> parser to read in and interpret
> these arguments and handle syntax errors, missing arguments, duplicated
> flags and the like.  Boost's program_options library handles
> command-line arguments without fuss."
>
> "Writing user-defined input and output streams can be tricky.  The Boost
> iostreams library gives the user easy access a range of useful
> functionality, including data encryption, compression in various
> standard formats, line-ending conversion and output in XML format."
>
> "C++ allows for casting between similar types, such as int and double.
> The Boost conversion library extends what is possible with casting,
> enabling the user to cast integers to strings and vice versa, and to
> cast safely between polymorphic types."

It would be better if each library had a generalized explanation of its
advantages similar to what you have written above, with possible links
from the main Boost page, than just a number of blurbs for a number of
different libraries on the main page.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

Paul Giaccone
Edward Diener wrote:

>Paul Giaccone wrote:
>  
>
>>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?  
>>Because, in some areas, C++ is deficient, is difficult to use or expects
>>too much of the programmer. Boost helps by providing what is useful but
>>missing and takes a lot of the work out of C++ programming.
>>
>>"Essentially, Boost needs to sell itself as something that no C++
>>programmer would want to be without. Think how the adman would write it:
>>"C++ getting you down? Spending hours tracking down that memory leak?
>>Then try Boost! It will change your life!" Well, maybe not, but
>>something along these lines would certainly go a long way to showing why
>>anyone should be using Boost. At the moment, the front page tells me is
>>that the libraries are free, portable, peer-reviewed and work well with
>>the C++ standard library, but that doesn't tell me why it is to anyone's
>>advantage to use them."
>>
>>David Abrahams of Boost Consulting, who started the thread, suggested
>>that I write a paragraph for a selection of Boost libraries that did
>>just this.
>>
>>Below is what I came up with, from my experience as a Boost user who has
>>used the libraries mentioned.  I think it would be helpful to both users
>>and developers if this text or something similar could be included on
>>the front page of boost.org or some other prominent place on the
>>website.  For myself, if I had seen something like this content on the
>>front page, I would have rushed to download the libraries.  What do you,
>>as the developers, think of this proposal?
>>
>>Keep up the excellent work.
>>
>>Paul Giaccone
>>
>>"Memory allocation on the heap in C++ requires the programmer to manage
>>the memory, make sure that there is always at least one pointer to the
>>memory and deallocating
>>    
>>
>
>deallocate
>
>  
>
>>it at the right time.  It is easy to forget to
>>do this or to do it in the wrong place in the code, which causes memory
>>leaks, or, worse, program crashes.  Boost makes life easier for the
>>programmer by providing various 'smart pointers' that automatically
>>maintain memory allocated on the heap, deallocating it at the right time
>>and requiring minimal intervention from the user."
>>
>>"A programmer wanting to read and write structured data (such as the
>>member variables of a class) to file can run into a number of problems.  
>>How should the data be formatted when written to file?  Do the read and
>>write functions correspond exactly?  If the structure of the data
>>changes in future releases of the program, will it still possible to
>>read files that were written using the old format?  Are files written on
>>one platform readable on another?  How should pointers be handled?  
>>Boost provides a serialization library that manages all of these
>>problems and more simply and elegantly."
>>    
>>
>
>,and more,
>  
>

Yes, I had "all of these problems and more" in there in an earlier
edit.  That sounds good.

>  
>
>>"In standard C++, handling multiple command-line arguments usually
>>requires the user to write a bespoke
>>    
>>
>
>bespoke ?
>
>  
>
It means "custom-made", which might be a better term.  The parser is
bespoke because the user has to write one specifically for the job in
hand that is not reusable.

>>parser to read in and interpret
>>these arguments and handle syntax errors, missing arguments, duplicated
>>flags and the like.  Boost's program_options library handles
>>command-line arguments without fuss."
>>
>>[...]
>>
>It would be better if each library had a generalized explanation of its
>advantages similar to what you have written above, with possible links
>from the main Boost page, than just a number of blurbs for a number of
>different libraries on the main page.
>
>  
>
This is intentional.  The idea is to give people a flavour of what Boost
can do for users and what they would gain from using it, which the
homepage currently does not do.  This would not be the place for an
introduction to all of the libraries - a potential user can find those
by digging deeper into the website.  Of course, there could be a
paragraph like the ones above for each of the libraries at the start of
each section (in http://boost.org/doc/html/*.html) to show the
interested user what each library has to offer.

Paul


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

David Maisonave
In reply to this post by Paul Giaccone
"Paul Giaccone" <[hidden email]> wrote in message
news:<[hidden email]>...
> 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?

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

Matt Doyle-3
In reply to this post by Paul Giaccone


> -----Original Message-----
> From: [hidden email]
> [mailto:[hidden email]]On Behalf Of David Maisonave
> "Paul Giaccone" <[hidden email]> wrote in message
> news:<[hidden email]>...
> > 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}

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Please don't overquote (was: why use Boost?)

David Abrahams
In reply to this post by Paul Giaccone
Paul Giaccone <[hidden email]> writes:

<quoting most of the foregoing long message>

Let's try to limit quoted text to what's relevant, please.

--
Dave Abrahams
Boost Consulting
www.boost-consulting.com

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

Nigel Stewart
In reply to this post by Matt Doyle-3

>> 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
_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

Oliver Kullmann
In reply to this post by Matt Doyle-3
On Thu, Feb 02, 2006 at 08:32:30AM -0800, Matt Doyle wrote:

>
>
> > -----Original Message-----
> > From: [hidden email]
> > [mailto:[hidden email]]On Behalf Of David Maisonave
> > "Paul Giaccone" <[hidden email]> wrote in message
> > news:<[hidden email]>...
> > > 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 ...
_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

Arkadiy Vertleyb
In reply to this post by Paul Giaccone
"Paul Giaccone" <[hidden email]> wrote

> "Essentially, Boost needs to sell itself as something that no C++
> programmer would want to be without. Think how the adman would write it:
> "C++ getting you down? Spending hours tracking down that memory leak?
> Then try Boost! It will change your life!" Well, maybe not, but
> something along these lines would certainly go a long way to showing why
> anyone should be using Boost.

While I completely agree, I can't help but mention that people fluent in
this kind of language are rarely found among those involved into open source
development :-)

Regards,
Arkadiy





_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

David Abrahams
In reply to this post by David Maisonave
"David Maisonave" <[hidden email]> writes:

> 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?

A short while ago we created the position of Boost Documentation
Wizard to help address this issue
(http://lists.boost.org/Archives/boost/2005/09/93946.php),
(http://lists.boost.org/Archives/boost/2005/10/96025.php).
Unfortunately, I think Rob Stewart just became too busy to make the
contribution he wanted to.  Perhaps you'd like to step up?

--
Dave Abrahams
Boost Consulting
www.boost-consulting.com

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

David Abrahams
In reply to this post by Matt Doyle-3
"Matt Doyle" <[hidden email]> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

Andy Little
In reply to this post by David Maisonave

"David Maisonave"  wrote

> 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?

You cant escape the fact that writing documentation is the most tedious, rotten,
boring, miserable, mind-numbing job imaginable ***. Thats why so much
documentation is bad or non-existent. Thats why some library is "nearly
finished"  after even a couple of years "except for the documentation", which is
going to be started "very soon now"

OTOH you are absolutely right.  I think a lot of projects suffer or even die out
because they didnt tackle documentation. They just leave it too late.

BTW Quickbook:

http://www.boost.org/tools/quickbook/doc/html/index.html

 is great for simplifying the task of writing documentation, IF you can get over
the hurdle of installing all the myriad weird and wonderful dependencies. I have
no idea about DocBook or XML but I have found if I just copy someones  Quickbook
jamfile and do bjam --v2 in my doc directory, all my docs seems to get built)  I
think  the Quickbook documentation has been sparse too but looks like its being
fleshed out for boost_1_34_0.

***I'm doing documentation at the moment, so I know what I'm talking about  :-(

regards
Andy Little





_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

David Maisonave
In reply to this post by Paul Giaccone
"Andy Little" <[hidden email]> wrote in message
news:<drtp38$3tu$[hidden email]>...
>
> "David Maisonave"  wrote
>
> > 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?
>
> You cant escape the fact that writing documentation is the most
> tedious, rotten, boring, miserable, mind-numbing job imaginable ***.
> Thats why so much documentation is bad or non-existent. Thats why some

> library is "nearly finished"  after even a couple of years "except for

> the documentation", which is going to be started "very soon now"

Personally, to me the hardest part of doing documentation, is getting it
started.
Once I do get it started, the rest is not so painful.

That's why I think it's important to have a really good template that
can give developers a good starting point.
One that can be a fill in the blank type.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

David Maisonave
In reply to this post by Paul Giaccone
"David Abrahams" <[hidden email]> wrote in message
news:<[hidden email]>...
> "David Maisonave" <[hidden email]> writes:
>
> > 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?
>
> A short while ago we created the position of Boost Documentation
> Wizard to help address this issue
> (http://lists.boost.org/Archives/boost/2005/09/93946.php),
> (http://lists.boost.org/Archives/boost/2005/10/96025.php).
> Unfortunately, I think Rob Stewart just became too busy to make the
> contribution he wanted to.  Perhaps you'd like to step up?


Actually, I would rather invest the time in creating an automated
documentation wizard.


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

David Abrahams
In reply to this post by Andy Little
"Andy Little" <[hidden email]> writes:

> "David Maisonave"  wrote
>
>> 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?
>
> You cant escape the fact that writing documentation is the most tedious, rotten,
> boring, miserable, mind-numbing job imaginable ***.

I disagree.  Finding the right way to explain something deepens one's
own understanding of it and -- very often -- uncovers real problems
with the design.  I think the skills required are really essential to
becoming a great software designer.  If you give it the time it
deserves and treat it as part of the process rather than just
something to do after you've written the code, it can even be
enjoyable.

It may be awful for some people, but it doesn't have to be so for
everyone.  Your statement is just a little bit too self-fulfilling for
my taste ;-)

> Thats why so much documentation is bad or non-existent. Thats why
> some library is "nearly finished" after even a couple of years
> "except for the documentation", which is going to be started "very
> soon now"

I think that happens in part because people don't appreciate what they
can get out of doing the documentation work.

--
Dave Abrahams
Boost Consulting
www.boost-consulting.com

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

Edward Diener
In reply to this post by Arkadiy Vertleyb
Arkadiy Vertleyb wrote:

> "Paul Giaccone" <[hidden email]> wrote
>
>> "Essentially, Boost needs to sell itself as something that no C++
>> programmer would want to be without. Think how the adman would write it:
>> "C++ getting you down? Spending hours tracking down that memory leak?
>> Then try Boost! It will change your life!" Well, maybe not, but
>> something along these lines would certainly go a long way to showing why
>> anyone should be using Boost.
>
> While I completely agree, I can't help but mention that people fluent in
> this kind of language

What kind of language ? Do you mean writing correct English ? If one's
primary language is not English I can well understand this, but if one's
primary language is English it is that person's own fault that he/she
can not write English well enough to be understood by others.

Being very fluent in English myself, I have volunteered in the past to
help other Boost developers write better English but since no one has
ever taken me up on it, I do not think it is acceptable to claim that
the inability to write English is a stumbling block to writing decent
documentation.

> are rarely found among those involved into open source
> development :-)

Perhaps those people should then try to educate themselves more. Is it a
goal of open source developers, whose primary language is English, to be
proud of the fact that they can write excellent code but can not
communicate effectively in their own language ?

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

Martin Wille
In reply to this post by Paul Giaccone
Paul Giaccone wrote:

[...]

What you wrote is probably a result of enthusiasm. However, I have to
object strongly to some parts of your message.


> "What the site needs, in my view, on the front page is some sort of
> material selling Boost.

This is nonsense. We don't need to "sell" Boost.


                              Why was Boost set up in the first place?

This information is on the front page in the first section.


> Because, in some areas, C++ is deficient, is difficult to use or expects
> too much of the programmer. Boost helps by providing what is useful but
> missing and takes a lot of the work out of C++ programming.

That's blah-blah. Every library is supposed to provide something that is
useful but missing and to take work out of programming.



> "Essentially, Boost needs to sell itself as something that no C++
> programmer would want to be without.

[stronger wording self-censored] This is nonsense. Boost does not need
to sell itself or to be sold by anyone. People are free to use Boost
libraries or not, at their own (or their boss') will.


                                    Think how the adman would write it:
> "C++ getting you down? Spending hours tracking down that memory leak?
> Then try Boost! It will change your life!" Well, maybe not, but
> something along these lines would certainly go a long way to showing why
> anyone should be using Boost.


Frankly, you seem to be an evangelist (in the worst sense of that word)
on a mission here. I strongly object to this attitude.

Anything like that on any Boost web page would strongly discourage
contributing to Boost, at least in my case.


                               At the moment, the front page tells me is
> that the libraries are free, portable, peer-reviewed and work well with
> the C++ standard library, but that doesn't tell me why it is to anyone's
> advantage to use them."

This is very essential and useful information, though. It names a lot of
advantages Boost has over many other libraries. Just consider the many
expensive and/or restrictively licensed, non-portable libraries of
questionable quality you have seen.

The front page also tells us that Boost libraries have been written with
standardization in mind and that standardization is in progress for
certain subset of Boost libraries. This already describes a very good
reason to delve into Boost.

The existing front page also tells us that Boost has a hassle-free
license, which certainly is also an advantage.


> David Abrahams of Boost Consulting, who started the thread, suggested
> that I write a paragraph for a selection of Boost libraries that did
> just this.

This is not a bad idea.


> Below is what I came up with, from my experience as a Boost user who has
> used the libraries mentioned.  I think it would be helpful to both users
> and developers if this text or something similar could be included on
> the front page of boost.org or some other prominent place on the
> website.  For myself, if I had seen something like this content on the
> front page, I would have rushed to download the libraries.  What do you,
> as the developers, think of this proposal?

We discussed this earlier on this list. The tendency seemed to be
towards a separate page linked from the front page (at least in my
perception; we didn't vote).

The complete text you suggest is definitely way too much for the front page.

What do you think of teasers: if technically feasible, a box with a
single section describing the advantage of one Boost library could be
put on the front page. The library described would be selected randomly.
This would give the page a dynamic touch and it would also stimulate
curiosity. Similar things could be done for "Who uses Boost" and for
"What do people say about Boost".


> "Memory allocation on the heap in C++ requires the programmer to manage
> the memory, make sure that there is always at least one pointer to the
> memory and deallocating it at the right time.  It is easy to forget to
> do this or to do it in the wrong place in the code, which causes memory
> leaks, or, worse, program crashes.  Boost makes life easier for the
> programmer by providing various 'smart pointers' that automatically
> maintain memory allocated on the heap, deallocating it at the right time
> and requiring minimal intervention from the user."

Please, keep in mind that memory is, to some extent, easier to manage
than other resources. The smart pointers are extremely useful for
managing other types of resources, too.

Also, programmers are aware of memory management issues. I don't think
they need a long explanation.


> "A programmer wanting to read and write structured data (such as the
> member variables of a class) to file can run into a number of problems.  
> How should the data be formatted when written to file?  Do the read and
> write functions correspond exactly?  If the structure of the data
> changes in future releases of the program, will it still possible to
> read files that were written using the old format?  Are files written on
> one platform readable on another?  How should pointers be handled?  
> Boost provides a serialization library that manages all of these
> problems and more simply and elegantly."


The introduction is too long in this paragraph. Programmers usually know
about the difficulties of serialization. If they don't then they will
likely not understand the advantages of Boost.Serialization, anyway.


  > "In standard C++, handling multiple command-line arguments usually
> requires the user to write a bespoke parser to read in and interpret
> these arguments and handle syntax errors, missing arguments, duplicated
> flags and the like.  Boost's program_options library handles
> command-line arguments without fuss."

I don't like this wording. It seems to be addressed to programmers.
Programmers tend not to be interested in arguments like "handles
command-line arguments without fuss" presented without any technical
backing.


> "Writing user-defined input and output streams can be tricky.  The Boost
> iostreams library gives the user easy access a range of useful
> functionality, including data encryption, compression in various
> standard formats, line-ending conversion and output in XML format."

How about:

"Boost.Iostreams simplifies the implementing of user-defined streams by
wrapping itself around compositions of simple user-defined classes that
model sources, sinks or filters of data. Boost.Iostreams also offers
ready to use classes for conversion of line-endings, filtering of
regular expressions, compression, dealing with native OS file handles,
and for other purposes."


Regards,
m
Send instant messages to your online friends http://au.messenger.yahoo.com 
_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

Nigel Stewart
In reply to this post by David Abrahams

> A short while ago we created the position of Boost Documentation
> Wizard to help address this issue
> (http://lists.boost.org/Archives/boost/2005/09/93946.php),
> (http://lists.boost.org/Archives/boost/2005/10/96025.php).
> Unfortunately, I think Rob Stewart just became too busy to make the
> contribution he wanted to.  Perhaps you'd like to step up?

    If Rob Stewart is agreeable, perhaps the position could
    be re advertised?

Nigel

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

Nigel Stewart
In reply to this post by David Abrahams
(A)
>> You cant escape the fact that writing documentation is the most tedious, rotten,
>> boring, miserable, mind-numbing job imaginable ***.

(B)
> I disagree.  Finding the right way to explain something deepens one's
> own understanding of it and -- very often -- uncovers real problems
> with the design.  I think the skills required are really essential to
> becoming a great software designer.  If you give it the time it
> deserves and treat it as part of the process rather than just
> something to do after you've written the code, it can even be
> enjoyable.

    After spending 10 years now on my PhD I can honestly say
    that both (A) and (B) are completely true, from my point of view. :-)

Nigel
_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Why use Boost?

Matt Doyle-3
In reply to this post by Paul Giaccone


> -----Original Message-----
> From: [hidden email]
> [mailto:[hidden email]]On Behalf Of David Abrahams
> "Matt Doyle" <[hidden email]> 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?
Well, I don't know if there is a silver bullet. I guess I would propose a section that could become a repository of "real life" examples. Not too far from the "who's using Boost" idea, have an area where users can upload examples of problems they had that Boost helped them solve. It would also serve Nigel's idea of a Boost cookbook. A solution center where people can come looking for ideas.

Now I hear the question - how is digging through a solution repository better than digging through the docs? Human nature perhaps? As likely as not finding and implementing the right tool for the job is going to take changing your pre-conceived approach to some degree. If your pre-conceived approach is that problem must be solved using method A then it's unlikely you look at the correct one (B). But, now if you see a problem the look just like yours, and it's being solved with method B, not A, then the pre-conceived notions (hopefully :) go out the window.

How's something along those lines sound?
   
>
> > 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?
oops, it obviously s/b implicit. My fingers don't always know what my brain is thinking :/

 


Scanned by McAfee GroupShield {X3BTB534}

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
123