"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 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?
"David Maisonave" <dmaisonave@commvault.com> 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
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
Nigel Stewart <ns@fluent.com> writes:
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?
It was never advertised in the first place; the moderators solicited Rob's help because he was offering excellent detailed critiques of documentation on a regular basis. Now I wonder if it wouldn't have been better to have left him doing what he did very well -- and had time for -- and tried to get someone else to manage the whole process. There's nothing like asking too much of a person to turn a great volunteer contribution into no contribution. Or maybe his absence has nothing to do with that at all. I don't know what Rob thinks about the future of this position; I'll ask him. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
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?
I don't think I can give the kind of time it would take to do what Rob wanted to do, however, I would be happy to volunteer to work with developers to create or improve documentation. I'm part of the current effort on Boost.Test, and it could be a useful way for me to learn far more about what Boost has to offer. Possibly, we should create some resource so any developer looking for this kind of help has a centralized reference point where there is a list of who to contact? John Phillips
John Phillips <phillips@mps.ohio-state.edu> writes:
I don't think I can give the kind of time it would take to do what Rob wanted to do, however, I would be happy to volunteer to work with developers to create or improve documentation. I'm part of the current effort on Boost.Test, and it could be a useful way for me to learn far more about what Boost has to offer.
Possibly, we should create some resource so any developer looking for this kind of help has a centralized reference point where there is a list of who to contact?
Fantastic. Why don't you start a page on the Wiki? -- Dave Abrahams Boost Consulting www.boost-consulting.com
"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
"Andy Little" <andy@servocomm.freeserve.co.uk> 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
(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
On Thu, 02 Feb 2006 16:36:16 -0500 David Abrahams <dave@boost-consulting.com> wrote:
I think that happens in part because people don't appreciate what they can get out of doing the documentation work.
I think it is more akin to the tools available to help write good documentation. We have seen marked improvement over the years, but the doc tools are still pretty lame. The ones that seem to be nicer require jumping through many hoops of configuration just to try them out. That's why I like doxygen. Yes, it has problems, but it is super easy to setup and start using.
"David Abrahams" wrote
"Andy Little" writes:
I think that happens in part because people don't appreciate what they can get out of doing the documentation work.
:-) :-) David, David, David. I just fell off my chair laughing!. Who had to start Your documentation for implicit_cast which has been lying around waiting to be done for years ? :-) regards Andy Little
"Andy Little" <andy@servocomm.freeserve.co.uk> writes:
"David Abrahams" wrote
"Andy Little" writes:
I think that happens in part because people don't appreciate what they can get out of doing the documentation work.
:-) :-)
David, David, David. I just fell off my chair laughing!. Who had to start Your documentation for implicit_cast which has been lying around waiting to be done for years ?
You _almost_ have a point, but don't forget, I just put that into Boost as an implementation detail of something else I was doing. I thought that maybe, someday, it would make sense to release it for public consumption. It was just a question of how much time I had to get a different job done, nothing more. -- Dave Abrahams Boost Consulting www.boost-consulting.com
"David Abrahams" wrote
"Andy Little" writes:
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.
This is true, very true but that isnt an enjoyable feeling. IDocumentation is hard work in itself, but it feeds back to the design, so now you need to redo the design and redo existing documentation. Its a vicious circle.
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.
I think that quote would make a great introduction to <more/writingdoc/introduction.html>. Looking at the current introduction I certainly dont get the feeling that its any more than a chore. I'm almost inspired by your last paragraph myself ;-)
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 ;-)
I shall mediate on your words and attempt to attack my documentation with renewed vigour! regards Andy Litte
David Abrahams wrote: "Andy Little" [1]<andy@servocomm.freeserve.co.uk> 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. I agree, though I was dragged kicking and screaming into agreement by experiences of the past few years. It's one thing to explain a design to other people who are already familiar with the topic (but not intimately so), but explaining how to use a functional language interpreter to someone whose programming expertise has been on-the-fly gawk scripting... the design of both the language and the interpreter has to become far more elegant than if I were explaining it to another person with my background. (Just try explaining to someone who's used to Perl/gawk why the new script language has no variables.) In fact I find consistently that if a design is elegant, then it's far more enjoyable to have explained it - whether in a TeX file or verbally - and the act of explaining forces me into knowing the topic better than before. (ObPhilo: I think that's because there's something that intrinsically beautiful about asymptotically exact invariant observations - I mean "good design".) As a novice to Boost, I'd offer to help out with the documentation except that not only are the next 6 to 8 weeks are bad timing for starting any projects like this, but I'm also notoriously slow at generating documentation. I'll keep an eye on this thread though, and if things resolve themselves favorably for me then I could see myself offering to help. References 1. mailto:andy@servocomm.freeserve.co.uk
participants (7)
-
Andy Little -
Brian Allison -
David Abrahams -
David Maisonave -
Jody Hagins -
John Phillips -
Nigel Stewart