Boost logo

Boost :

From: John Phillips (phillips_at_[hidden])
Date: 2008-04-17 16:41:55


   Sorry this is not a full review. I had a half an hour to dedicate to
this, and that just isn't enough time for the library.

   First, I want to say that I find some of the possibilities of this
library intriuging, and whatever the outcome of this review I hope to
see some form of it in boost in the future.

   However, I find the documentation difficult to read. Some of this is
because of grammatical considerations. For this part of the
documentation, I suggest the author works with any of the various people
on this list who have offered to assist with ddocumentation in the past.
I think there are still some offers with contact information that can be
found on the wiki.

   The other problem I have with the documentation is that the author
seems to know what he is talking about well enough that he doesn't
realize that it is not complete enough for many potential readers. For
this I have two suggestions. The first is to include more examples in
the flow of the documentation. Some of them should betrivial, while
others show more complete use cases. Every time a new concept or use is
introduced, consider how an example could improve the discussion. This
has become a hazard in the Boost community because we are all far more
steeped in functional programming concepts and practices than the
general run of C++ programmers and this leads to a communications
disconnect for what we think is clear documentation compared to what the
mainstream community needs for clear documentation.

   My second suggestion is to think a lot about how to reorganize the
documentation with a new user of the library in mind. If someone comes
to the library without knowing what you are doing, how can you show them
each of the advantages of the library, preferably one at a time? How can
you build the ddocs to draw them through that process and to make it
obvious what parts of the library will help solve what problems for the
user?

   An example is the "How to Read the Docs" section at the bottom of the
Quick Start page. The reader is two pages into the docs, and a new
reader who doesn't understand will have already given up before getting
to this section. Separate it and make it clear where to find it in the
ToC, instead of hiding it in another page.

   I haven't looked at the implementation enough to have a usable
opinion, so I can really only talk about the documentation. In my
opinion, the docs need substantial improvement before the library should
be accepted, and I strongly encourage the author to make those
improvements whatever the outcome of the review.

                        John Phillips


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk