[boost] Documentation (was Re: [log] how to set attributes under multi-threaded application)

Subject: [boost] Documentation (was Re: [log] how to set attributes under multi-threaded application)
From: Dean Michael Berris (mikhailberis_at_[hidden])
Date: 2011-08-04 17:20:04

On Fri, Aug 5, 2011 at 3:13 AM, Sean Chittenden <sean_at_[hidden]> wrote:
>
>
> This is a general comment about the documentation across the boost project and isn't entirely specific to the boost-log project, but wisdom such as this "the application of XYZ feature is ideally suited for the situation ABC" doesn't exist frequently in much of the boost documentation. I don't know if it's in some style guideline someplace, but having been a boost user for ~5yrs now and having forced boost on other developers for a few years now, this is one of the things that I acutely notice/get push back on regarding the boost project (especially when referencing its documentation).
>
> I actually just made this comment to Boris, the author of the "Boost Libraries" that one of the things that I like about his book is it actually distills practical examples because the boost docs are more geared toward other Boost developers vs consumers of the libraries. The biggest piece of feedback I get is summed up as, "Boost is high quality, but it requires a high degree of skill to apply. A lot of this is because the docs are frequently very dense and assume equivalent levels of STL competency to decipher what's written. Nine times out of ten, I don't need to customize boost or extend it, I just need to use it and there isn't something that I can easily reference and get what I'm looking for within 15-30min." And I'll admit, it took a good year of hammering away at examples and stubbing out little bits of code here and there before I became familiar and comfortable with implementing boost. Call it a byproduct of the PHP-ization of developers, I dunno, but I think there
> Â 's a nugget of truth to be had in there (maybe add a quickbook type called "Implementors" with tips/hints? *shrug*).
>

FWIW, I try to do this in cpp-netlib and I have to agree with Andrey's
assertion that this is not practical nor sustainable. It's actually
one of the things that I'm thinking of "fixing" as far as the
documentation is concerned.

I think a library's documentation should surface three things in general:

1) Why the library exists.
2) How to use the library.
3) Expose important details that may not otherwise be obvious in the API.

I think if #1 and #2 are done properly then I'd say examples of usage
would be mere gravy. Because all if not most of Boost libraries tend
to be fairly generic or broad (sometimes both) I'd say explicitly
saying "This library can be used in <insert situation X>" greatly
limits the applicability and/or perceived utility of the library.

Just my $0.02.

--
Dean Michael Berris
http://about.me/deanberris