On 08/04/2011 09:13 PM, Sean Chittenden wrote:
This is a general comment about the documentation across the boost project and isn't entirely specific to the boost-log project, but wisdom such as this "the application of XYZ feature is ideally suited for the situation ABC" doesn't exist frequently in much of the boost documentation. I don't know if it's in some style guideline someplace, but having been a boost user for ~5yrs now and having forced boost on other developers for a few years now, this is one of the things that I acutely notice/get push back on regarding the boost project (especially when referencing its documentation).
[snip]
Anyway, Andrey, it'd be keen if you could include a note along these lines in the docs. Maybe a quickbook type for "Implementors."
Well, although I admit that new users of Boost and Boost.Log in particular may be missing this kind of case-by-case style docs, this approach is just not practical. Boost libraries are known for their flexibility, even the author doesn't always know in what ways his library is going to be used. Describing each case in the docs will take ages, the resulting docs will be too large to comprehend and there will still be lots of users with their cases not being covered. I think the common formula "library design + tutorial + features description + reference" is the golden middle for medium-sized projects, like Boost.Log. Also, quite a few common case examples will help to get things started. The rest will come with experience. As a side note, this kind of scenario-based description or "words of wisdom" is probably better suited for books and articles rather than library docs. I'm not saying it's useless (just the opposite, actually), it's just not what I usually seek in the library docs.