Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Andrew Hundt (athundt_at_[hidden])
Date: 2013-10-10 15:00:10

On Thu, Oct 10, 2013 at 12:20 AM, Robert Ramey <ramey_at_[hidden]> wrote:

> Jeff Flinn wrote:
> > On 10/9/2013 12:41 PM, Robert Ramey wrote:
> >> Daryle Walker wrote:
> >>>> From: ramey_at_[hidden]
> > 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_containers.html#container.non_standard_containers.static_vector

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_reference.html#header.boost.container.static_vector_hpp

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 libraries<http://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