On Thu, Feb 02, 2006 at 08:32:30AM -0800, Matt Doyle wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org]On Behalf Of David Maisonave "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 <snip> 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.
I think it would help a lot (and would be relatively easy to establish) if every boost library documentation would have a devoted example section (I mean, real text there, not just a file), and there we would find *many simple* examples. Too often either we don't have examples, or there is one which is already quite complicated --- those are alright for later, but for the beginning we want to see simple examples, and quite a few of them. In this way one easily gets a first feeling how to use it and what to expect. Oliver P.S. A system which perfectly implements the "only-convoluted examples to show off" system is the R system; I believe that in those 5 years I'm using it (occasionally) I have never ever found any example which gave me anything; yet Boost doesn't reach that level, but with a little effort ...