Hi, Andrey Semashev said: 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.
I would like to give my limited feedback with the log docs about this very point : What I think might be a bit overhelming and don't help beginners with boost.log is the library design page itself. http://boost-log.sourceforge.net/libs/log/doc/html/log/design.html I mean the content organisation of the page, not the fact that it exists and I agree with you that it should be up front. The main problems with the page : A. there is a BIG bloc of text with almost no apparent hierarchy - that's a showstopper for a lot of people that will just click the "tutorial" link to see what it's really about; B. the scheme is clear technically but might be easier to read if it was to be read from left to right instead of right to left (at least because it uses english text); an alternative would have been from top to bottom : reading the scheme should follow the way data goes from loggers to sinks (in fact the current scheme looks like an inverted comics page to me...) Here are some suggestions to improve this page : 1. Structure the big block of text in several distinct parts, with titles. I think those parts already exists but they just lack obvious separations like just big titles. 2. Add links in the text to definitions from the previous page (Definitions). Reading the definitions first doesn't always make things really clear immediately. Often you read them used in context and then understand...or not if your forgot what it was. There are 9 definitions with several having the same beginning. It might be easier to the user to link to those simple definitions when they need them, when reading the library design text (might not be necessary after that?). 3. Invert the reading sens of the scheme or make it top to bottom. Obviously I'm an humble user, not an authority in the matter, but I hope it helps getting more users not stop at this page. Joël Lamotte