[boost] Some notes on Egg

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