[boost] [log] Documentation improvement suggestions - was :how to set attributes under multi-threaded application

Subject: [boost] [log] Documentation improvement suggestions - was :how to set attributes under multi-threaded application
From: Klaim - Joël Lamotte (mjklaim_at_[hidden])
Date: 2011-08-04 17:37:06

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