Re: [boost] [log] Documentation improvement suggestions

Subject: Re: [boost] [log] Documentation improvement suggestions
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2011-08-04 20:45:11

On 08/05/2011 01:37 AM, Klaim - Joël Lamotte wrote:
> Hi,
>
> 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.

Thanks, that is a most useful feedback. Yes, that page could use some 
improvement. I'll try to do something before the v2 release.

Regarding the note about definitions. Does anyone know if it's possible 
to make a tooltip in quickbook?