On Thu, Oct 10, 2013 at 12:20 AM, Robert Ramey
Jeff Flinn wrote:
On 10/9/2013 12:41 PM, Robert Ramey wrote:
Daryle Walker wrote:
From: ramey@rrsd.com I wish this thread had come up 3-4months ago. Unlike you I couldn't grok the docs to use multi-array as a back end to a Qt table where I needed to support run time row/col insertion/deletion. I was under time constraints and found it much easier to build my own facilities. I'm not sure whether it was due to docs or design.
Well, I did come to understand it pretty well. But I really have to say I spent a LOT of time poring over the documentation, experimenting etc. The oddest thing to me is that now it seems easy to me and I can't figure out what I spent the time on - we're talking a few days. I had the same experience (only worse) with units library. Actually I have this experience with almost every boost library I use. This brings up the whole question of documentation of boost libraries and in fact documentation of computer libraries in general. I've spent a lot of time thinking about this lately. I feel we've been too lax in accepting libraries after the review whose documentation isn't up to some minimum standard (not that we have a standard).
Robert Ramey
+1 Every boost library I've used has been great once I've understood it. However, I have trouble getting some very smart people on my team to use existing boost tools because they find it confusing, and they also have a tough time finding the functionality they need. I believe this is a documentation problem. For example, a number of people I know were surprised when I told them that the /libs folder contains examples and unit tests for every library. The documentation doesn't seem to consistently provide links and explanations of each. I believe I spent months as a user before I found the libs folder. I'll take boost.container.static_vector, as an additional example. I contributed to it so it seems like a decent choice. Here are the two most easily accessible links in Boost.Container for documentation of static_vector: http://www.boost.org/doc/libs/1_54_0/doc/html/container/non_standard_contain... The first link contains the first block of text about static_vector I expect one would run into, and there isn't even a link to the class documentation! http://www.boost.org/doc/libs/1_54_0/doc/html/boost_container_header_referen... This second link is the typical header documentation throughout boost. When I first started using boost it was months before I realized that in these header synopsis I could click on the words of the class to see the full documentation of that class, in this case "static_vector". Much of the time I just felt confused and lost. I think this is indicative of a layout and user interface that needs some improvement. Now, perhaps I should blame myself for this in the static_vector case and fix it, but it is indicative of the general documentation problems. One example of C++ documentation I have found that I've actually been happy with is cppreference.com. If you look at their front page they have many of the major classes, and with one click you are in there reading what you want to know, with examples at the bottom of every page. It is actually entertaining that they mention boost documentation in their FAQ as follows: Why is the material here limited to the standard C and C++?
In short, we chose quality over quantity. Some boost librarieshttp://www.boost.org/ could also be candidates for inclusion though. While their tutorials are very good, the *reference* documentation is often very inflexible and inconvenient.
So, is there anything we can do about it? I remember a couple of years ago Boost had a "Bug Sprint" with the goal of closing lots of open tickets. Perhaps we should do a "documentation sprint"? Here is an interesting article about writing good documentation that also contains links to other solid articles that I recommend checking out: http://stevelosh.com/blog/2013/09/teach-dont-tell/ Cheers! Andrew Hundt