Re: [Boost-users] [boost] [Fit]Â formal review starts today

Subject: Re: [Boost-users] [boost] [Fit] formal review starts today
From: Gavin Lambert (gavinl_at_[hidden])
Date: 2016-03-09 00:38:37

On 9/03/2016 10:43, paul Fultz wrote:
>> I would hope to convince you that a good Overview of your library should
>> come first and then all the Quick Start guides, tutorials, examples etc.
>> would make much more sense once your end-user understands what your
>> library really does in terms of at least the main general functionality.
>
> I usually start with the Quick Start guide with a library in order to get an
> understanding of what components are in the library and what they can do, then
> I start delving into the other components from there. Thats what I am showing
> in the Quick Start guide.
>
> I guess people have different ways of learning a library. I wonder what is
> needed to be explained better in a initial overview of the library.

I suspect part of the problem is that the Introduction appears under the 
ToC at the top level instead of on its own page above the Quick Start. 
Thus someone not scrolling down is likely to miss the Introduction and 
start with the Quick Start.

Still, even the Introduction is a little light on the things an Overview 
generally needs to cover: "why should I consider using this library and 
what types of problems does it solve?"  (Sometimes some of this is split 
to a separate Motivation section.)

Quick Starts / Tutorials are more for answering "now that I've already 
decided to (probably) use this library, how do I do XXX?"