On Sat, Jun 11, 2011 at 06:54:57AM -0400, Edward Diener wrote:

> > On 6/10/2011 5:51 AM, Klaim - Jo?l Lamotte wrote:

> >> On Fri, Jun 10, 2011 at 05:39, Peter <lq.yan@siat.ac.cn
> >>     I'm a newer to boost library. when i try to use the boost library to
> >>     get the files of current directory, I found it is so difficult to
> >>     get some help from boost HTML document.
> >>     Is there any document could teach me to use boost library API? Most
> >>     of time,  i use visual studio, MSDN teach me how to use API.
> >>     So i think Boost maybe has similar documents to help me improving
> >>     coding speed.
> >>     --
> >>
> >>
> >> Hi Peter and welcome,
> >>
> >> Boost is a set of libraries, not only one library. You can think
> >> Boost is a "quality label" to make it more clear.
> >>
> >> That means that each library have it own purpose, might be totally
> >> independant of other Boost libraries and have an interface
> >> specifically thought to solve a specific kind of problem. So not all
> >> libraries can share the same interface.
> >>
> >> That also mean that each library have to have it's documentation
> >> separate from the others.
> >>
> >> As Boost is totally independant from companies like Microsoft, you
> >> can't
> >> (AFAIK) automatically provide a way to get the Boost documentation in
> >> MSDN browser.

> 
> I believe you lads are misunderstanding his original question. My interpretation is the following:
> 
> * When he refers to "MSDN teach me", he's referring to the ample amounts
>   of examples, snippets and proper articles present in the APIs documented
>   on the MSDN website/documentation.
> 
> * Most Boost library documentation is a bit sparse and unstructured when
>   it comes to the prose, and samples tend to just be code dumps, while on
>   MSDN they're typically interleaved with prose, describing things in more
>   detail.
> 
> You make some points about that each Boost library having its own documentation style, which makes it
> harder to find the relevant sections of the documentation you're interested in.
> 
> I know I personally avoid the iostreams and serialization docs solely due to the very hard to use expandos
> in the tree structure, and the impossibility to link to particular pages while retaining said navigation tree.
> 
> While it would be Good if all Boost docs was under the same documentation system (which some are),
> porting old docs to whatever system is in use now would probably be rather costly for little gain.
> 
> The IBD (Improving Boost Docs) got some progress in the past, but I'm unsure what the end results of their
> effort were.

It may not *yet* be apparent, but most new and upcoming libraries come with *much* better documentation, especially those using the Quickbook tool chain. (The Improving Boost docs program is only now yielding fruit, and the recently accepted AutoIndex will also increasingly provide the benefit of indexes quite soon).

IMO, some Boost libraries are examples of the best documentation - often much better than MSDN.

Having spent some time reworking an old library (Boost.Pool), I say that it was time-consuming and at the same time both mind-numbingly boring and yet testing ones knowledge of the details of the library (I found myself out of my depth!).

So if anyone is an reasonably expert user of an existing library and has some time to spare, now is the time to volunteer to upgrade its docs! Assistance getting started can be provided.

Paul