Jim Douglas
David Abrahams wrote:
What do you wish someone had explained to you? With what did you need hand-holding? Based on this feedback I expect to make some improvements to the Boost website, also. Any information you can give me will be much appreciated.
From my POV as a user and recent contributor my comments are:
1. It took me a long time for me to realise that a large proportion of Boost is header-only and can be used without pre-building any libraries (archives & shared objects).
2. It is also not immediately clear that there is a large amount of interdependency between Boost libraries. This information would be particularly useful when trying to resolve compilation problems e.g if Boost.b & Boost.c both use Boost.a, if you can't get 'a' to compile then you don't stand a cat in hell's chance with b and/or c.
We have to be careful about qualitative statements like that one. Compared to many large-scale libraries, Boost is highly decoupled.
IMHO it is high time that someone produced a dependency graph, or each library document had a "uses" section.
Do you know about http://www.boost.org/tools/bcp/bcp.html and its --report option? That's something I can cover in my talk.
3. Boost's sheer size makes it difficult to document. From the responses so far it's obvious that different users have their own personal favourite sections. I find that I discover something new every day, usually thinking "If only I had discovered that six months ago I could have saved so much time!"
The ultimate solution would be to have a problem oriented section in the docs, i.e. if you are trying to do this, then we suggest you try these libraries. If we assume that each library was constructed in order to fill a need and/or solve a problem (and not just for intellectual amusement) then these needs/problems could be collated into a single section.
Yeah... some libraries are so general-purpose (e.g. lambda, mpl, preprocessor) that it's hard for me to say anything that most people will identify as their use case. But if you could be more specific -- i.e. write some of it -- then maybe the rest of us could pick up on what you're doing and see how it would work.
4. The single word naming of the libraries can lead to ambiguities and misunderstanding e.g. "serialization" means different things to different people and requires a full paragraph to explain, and IMHO "thread" is somewhat misleading. Other names mean nothing to me so I have to go and look them up.
What would be better, "the boost serialization of a style espoused by Robert Ramey library?" ;-) -- Dave Abrahams Boost Consulting www.boost-consulting.com