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."
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.
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
Paul Giaccone <paulg@cinesite.co.uk> 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
"Paul Giaccone" <paulg@cinesite.co.uk> 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
Arkadiy Vertleyb wrote:
"Paul Giaccone" <paulg@cinesite.co.uk> 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 ?
Edward Diener <eddielee@tropicsoft.com> writes:
Arkadiy Vertleyb wrote:
"Paul Giaccone" <paulg@cinesite.co.uk> 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 ?
I think he was talking about marketing-speak :) -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Thu, 02 Feb 2006 16:54:46 -0500 Edward Diener <eddielee@tropicsoft.com> wrote:
Arkadiy Vertleyb wrote:
"Paul Giaccone" <paulg@cinesite.co.uk> 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
I do not think "this kind of language" is in reference to the English language, but to the "language of advertisers."
"Edward Diener" <eddielee@tropicsoft.com> wrote
Arkadiy Vertleyb wrote:
"Paul Giaccone" <paulg@cinesite.co.uk> 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 ?
No, I don't mean 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
This is very much appreciated...
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.
Well, this is not about documentation... This is about the "language" sales people use to convince kids that Coca-cola and chips is the best food in the world. I believe this kind of language is pretty much international. I do agree with Martin Wille that this kind of advertisement may have a negative rather than positive effect, especially when the developers are concerned. Regards, Arkadiy
Arkadiy Vertleyb wrote:
"Edward Diener" <eddielee@tropicsoft.com> wrote
Arkadiy Vertleyb wrote:
"Paul Giaccone" <paulg@cinesite.co.uk> 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 ?
No, I don't mean 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
This is very much appreciated...
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.
Well, this is not about documentation... This is about the "language" sales people use to convince kids that Coca-cola and chips is the best food in the world. I believe this kind of language is pretty much international.
It may be "international" but it is worthless for serious programmers. What Boost might have is a paragraph, or two, on each implementation explaining to a programmer what the main functionality of the implementation is about and why one might want to use instead of current solutions which are part of either the C++ standard language or C++ standard library. I think this could be done in general terms without resorting to empty market hype, and would be an effective means of telling the programmer about the importance of a particular implementation before he delves into that implementation's specific documentation. While much of the Boost documentation is excellent, there is a tendency in some of it to start explaining details before a good general explanation is given, and this possibily results in discouraging programmers from using the implementation.
I do agree with Martin Wille that this kind of advertisement may have a negative rather than positive effect, especially when the developers are concerned.
If it's a sort of marketing hype, I agree. But there is room for a good general explanation of a library which sticks to technical elements and useful, practical functionality. There's no need to sell Boost but there could be a better way to make the general information about each implementation more easily understood. Whoever were to write a good general description of a particular implementation, if it were not done by one of the programmer's of that implementation, it would need to be signed off by one of them before appearing on a Boost web page.
"Paul Giaccone" <paulg@cinesite.co.uk> 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.
(Apologies for the messed-up indentation.) Some people seem to have taken my proposed advertising spiel seriously. Please note that I said "Well, maybe not, but something along those lines." The ad-speak was intended to be facetious but also to provoke discussion of the issue, which it clearly has.
Contrary to what some have said, Boost *does* need to be sold. The website currently does little to inspire the new user to want to use it. A few paragraphs like those I posted would draw the user in and have them downloading it in an instant. At the moment, I suspect that the keen user doesn't come to that realisation until they have browsed several pages, and the casually interested user will just not bother. You developed Boost because you want people to use it, so it makes a great deal of sense to tell them *why* they should use it, and not just how to. Paul
Paul Giaccone wrote: Some comments from a boost newbie/C++ old hand here.
Contrary to what some have said, Boost *does* need to be sold.
Well, that statement can mean a lot of things, but I believe you mean that it is not, as currently presented, attractive to new-comers. I hope you don't mean that it needs to be sold in an evangeligal manner. :-) Since the stated aim is to establish "existing practice", that's probably the best way of selling it, too.
The website currently does little to inspire the new user to want to use it.
This is, for me at least, true.
A few paragraphs like those I posted would draw the user in and have them downloading it in an instant.
But this isn't. You must tell me why and how Boost will help me. If I'm told that "all cool developers use Boost" I'm likely to shrug and relish in my lack of coolness.
At the moment, I suspect that the keen user doesn't come to that realisation until they have browsed several pages, and the casually interested user will just not bother.
Yup. BTDTGTTS.
You developed Boost because you want people to use it, so it makes a great deal of sense to tell them *why* they should use it, and not just how to.
Exactly. Now, look at the main page of the website. There's an introduction which establishes that Boost provides good libraries for C++ developers. Fine. What next? Oh, "Getting started", that'll tell me how do use Boost, right? Nope. Download from CVS? Prepare and build? What is this? So that's the introductory guide, then. Download a 10+ meg file, unpack it, build it (using a build system I've never seen before), and then I'm ready to use Boost. Ah, thanks, but no thanks. Even if I do follow the "Getting started" document, I'm still not ready to use Boost, because I haven't got a clue what I should use it for. That's not "Getting started", that's "Download, configuration and installation". "Getting started" should tell me what the different libraries can offer me. It should tell me how to make my applications and systems better by using Boost. It should tell me what the design philosophies are. The last part there is important, actually. There is a lot of really, really clever stuff in Boost. It's obviously been written and refined by very skilled developers, who think nothing of tackling metaprogramming and lambda expressions. And the average programmer, who barely uses anything but std::vector from the STL, will think that "this is for really brainy guys, I'll never understand it". There is an inherent conflict in Boost documentation, since it has two distinct target audiences. On the one hand, it's often written in the precise and formal style of the standard. This is understandable, as one of the stated aims is to extend the standard library. Information can be omitted by simply referring to a relevant section of the standard. But only a very small portion of C++ programmers know the standard by heart and can read that kind of prose without problems. That's you, and the regulars at comp.lang.c++.moderated and the standards committee. The rest of us prefer to read Sutter and Myers, since they can explain it to us in a way we can understand. Why not try to make an "Exceptional and Effective Boost", with items like "If you have pointers in your container, use indirect_iterator"? A standard documentation format would be useful, too. And a consistent content template: Introduction (interface layout) Requirements and usage guidelines How-to examples Reference Specification (this is the formal part) Design and implementation (optional) Then you'd know what to expect, it would be easy to find your way around and it would be easier for writers of new libraries, too. Just my 2c. Orjan
Orjan Westin wrote:
Paul Giaccone wrote:
Some comments from a boost newbie/C++ old hand here.
Contrary to what some have said, Boost *does* need to be sold.
Well, that statement can mean a lot of things, but I believe you mean that it is not, as currently presented, attractive to new-comers.
I hope you don't mean that it needs to be sold in an evangeligal manner. :-)
No, no; that wouldn't help anyone. Just in a way, like you suggested in the rest of your email, that makes the C++ programmer eagerly install it and then wonder where it has been all their life :)
Orjan Westin wrote: Paul Giaccone wrote: Some comments from a boost newbie/C++ old hand here. Contrary to what some have said, Boost *does* need to be sold. Well, that statement can mean a lot of things, but I believe you mean that it is not, as currently presented, attractive to new-comers. I hope you don't mean that it needs to be sold in an evangeligal manner. :-) Since the stated aim is to establish "existing practice", that's probably the best way of selling it, too. Can someone intelligently define for me what is being meant here by "evangelism"? I had thought it was the act of building a bridge for someome from their current world view to a different world view. 1) Why is there an apparant ignorance that this is not intrinsically a Bad Thing, when each of you started out as an infant without knowledge of the good/evil status of such bridge building? Am I observing some internal fear, or am I frighteningly ignorant of the proper use of the word "evangelism"? Or perhaps the world "charlatan" should be used? 2) If my understanding of 'evangelism' is correct - and please don't start talking religion to me, just stick to the word - then isn't that what is required to give someone a chance to see something in an attractive light which due to preconceived notions (of ignorance) they were before only able to see as something ugly? I thought I had evangelized a prior roommate who insisted to me that C++ was a Bad Idea, and that C could suffice for any program. By the end of the discussion he admitted that C++ could be useful, and a few weeks later he admitted that it was in fact useful in many intances. But I was neither brainwashing, nor was I being a charlatan and claiming that it'd <miracle of choice> for him. I was in fact evangelizing C++ to him.
Brian Allison wrote:
Orjan Westin wrote:
Paul Giaccone wrote:
Contrary to what some have said, Boost *does* need to be sold.
Well, that statement can mean a lot of things, but I believe you mean that it is not, as currently presented, attractive to new-comers.
I hope you don't mean that it needs to be sold in an evangeligal manner. :-)
Can someone intelligently define for me what is being meant here by "evangelism"?
When using the word I meant a proselytizing sell, focused on conversion, with little or no regard for whether what you are selling is actually fitting for the person you're selling to. I used that word because I wouldn't want a faith-based presentation, but one founded on facts and informed choice.
I had thought it was the act of building a bridge for someome from their current world view to a different world view.
www.dictionary.com gives two definitions of evangelism: 1. Zealous preaching and dissemination of the gospel, as through missionary work. 2. Militant zeal for a cause. I wouldn't expect someone who is evangelising according to one of the above definitions to concede that there may be other answers that are more fitting in some circumstances. For instance, I could use boost::spirit to parse a simple XML file, but I'd rather use expat and the C++ wrappers I wrote for it some years ago. It works, I know how it works, and it's quick and simple for me to include in my project. I don't think it would happen, which is why I put a smiley there, but it's concievable that some people would insist I use the boost library, since that's the "one true way", just like there are people who hold similar views on such "religious" issues as open source, free software, and Apple Macintosh. Hopefully that clarifies what I meant. While I'm posting anyway, it strikes me that one way to get people to use boost would be to ask Herb Sutter include it in the Visual C++ distribution, especially now that there is a free edition for hobbyists. And for my next trick, I'll don copper armour, climb to the top of a high mountain during a thunderstorm and shout that all gods are bastards. ;-) Orjan
Brian Allison <brian@dtmr.com> writes:
Orjan Westin wrote:
Paul Giaccone wrote:
Some comments from a boost newbie/C++ old hand here.
Contrary to what some have said, Boost *does* need to be sold.
Well, that statement can mean a lot of things, but I believe you mean that it is not, as currently presented, attractive to new-comers.
You know, the old trick with the leading >s that shows how many levels of reply are in play? http://www.boost.org/more/discussion_policy.htm#effective Thanks, -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote: Brian Allison [1]<brian@dtmr.com> writes: Orjan Westin wrote: Paul Giaccone wrote: Some comments from a boost newbie/C++ old hand here. Contrary to what some have said, Boost *does* need to be sold. Well, that statement can mean a lot of things, but I believe you mean that it is not, as currently presented, attractive to new-comers. You know, the old trick with the leading >s that shows how many levels of reply are in play? [2]http://www.boost.org/more/discussion_policy.htm#effective Thanks, Sorry, I think I was overly clever with my client, and it didn't show me the fruits of my cleverness. I think I've figured out where it was though, so I shouldn't be doing that again. (Though this message should [dis]prove my theory...) BTW - some of us are in a situation where we can only do e-mail from our desks and not read web pages. I'd have to copy the URL by hand, walk to another room and then enter it into a web browser on a machine not connected to our internal web. Barbaric, but true. :/ *shrug* References 1. mailto:brian@dtmr.com 2. http://www.boost.org/more/discussion_policy.htm#effective
Paul Giaccone <paulg@cinesite.co.uk> writes:
Contrary to what some have said, Boost *does* need to be sold. The website currently does little to inspire the new user to want to use it.
If I'm hearing you right, what you're really trying to say is that *potential users* of Boost really need Boost, and in order to get it, they need to be sold on it. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Paul Giaccone <paulg@cinesite.co.uk> writes:
Contrary to what some have said, Boost *does* need to be sold. The website currently does little to inspire the new user to want to use it.
If I'm hearing you right, what you're really trying to say is that *potential users* of Boost really need Boost, and in order to get it, they need to be sold on it.
Yup, that's it. In a nutshell, I mean selling it as: "Boost is a great help in many ways; C++ developers have a lot to gain by using it; here's why". Sorry if I didn't make it clear before. Paul
Arkadiy Vertleyb wrote:
"Paul Giaccone" <paulg@cinesite.co.uk> 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 :-)
Quite, so the trick is getting hold of those who have both the development skills (or rather, an intimate understanding of the libraries) and the language skills and asking them to write the documentation. I intend no disrespect to any of the developers, but isn't there an unwritten principle in program development that the developer shouldn't write the documentation because they are too close to the code to understand what the user requires from the docs? Ideally (and I stress "ideally", before anyone points out the impracticalities) there would be a Boost "superdeveloper" with knowledge of all the libraries and good writing skills who would write documentation for *all* the libraries, making it of uniform readability, usability and value to the user. Paul
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
participants (8)
-
Arkadiy Vertleyb -
Brian Allison -
David Abrahams -
Edward Diener -
Jody Hagins -
Martin Wille -
Orjan Westin -
Paul Giaccone