Re: [boost] Documentation for Boost libraries

From: Edward Diener (eldiener_at_[hidden])
Date: 2008-06-27 18:50:10

David Abrahams wrote:
> Edward Diener wrote:
> 
>> Today, looking for a socket library to use in my C++ code I decided to
>> look at the documentation for ASIO. I was shocked to find out that there
>> is no overview of the functionality of this library at all, but just a
>> series of tutorials and examples and then a reference listing a
>> multitude of classes.
>>
>> I do not believe this is adequate for explaining library functionality
>> and puts a totally unnecessary burden of the end-user when learning the
>> functionality of a library.
> 
> I just looked at the ASIO docs, and I have to agree that exposition of
> basic concepts is needed right from the beginning.  However, I think I
> did find much of what I'd want to know to get started with the library;
> it was buried in
> http://www.boost.org/doc/libs/1_35_0/doc/html/boost_asio/design.html

These are different notes about various ways functionality has been 
designed in the library, which is certainly useful, but they provide no 
high order overview of what functionality actually exists in the library 
and how the end user should use it.

 From the tutorials I would guess that the library, consisting of some 
120+ individual items as specified in the reference, has to do with 
using network sockets, in synchronous and asynchronous mode, and nothing 
else. Perhaps this is true but that is an awful lot of items just for 
dealing with socket programming in ASIO. Even here a good general 
introduction to socket programming with ASIO would have been welcome. Of 
course something tells me that there is more to the library than just 
network socket programming, but I do not have the patience to dig into 
this by looking at some 120 individual items to see what each one 
encompasses. Nor do I have the patience to try to figure out how those 
items relate to each other. This is what a good overview should do.

I view this documentation weakness as a real failure of explaining even 
the most basic things one wants to know about a library, and for this to 
happen in a Boost library seems really poor to me.

This is not meant to be a reflection on the programmer, Christopher 
Kohlhoff, nor on the implementation, for what little I can get from an 
initial perusal of the documentation the library seems useful. But it is 
not the way to write documentation for a Boost library and I am really 
surprised that the library was accepted with the documentation in the 
form that it has.

It is very important for developers to take a look at documentation from 
the end-users point of view, even when the end user is a programmer 
himself. Clearly the great majority of Boost libraries do this and 
provide the end-user with the necessary introduction/overview to 
understand the uses of a library. I do feel that the ASIO library, in 
its tutorials, has done this to a very limited degree.

I do understand that the developer's native language may not be English 
so that he was much more comfortable explaining the implementation by 
tutorials rather than a well organized overview