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

Subject: Re: [boost] [Boost-users] [Fit] formal review starts today
From: paul Fultz (pfultz2_at_[hidden])
Date: 2016-03-09 02:36:44

> On Tuesday, March 8, 2016 11:39 PM, Gavin Lambert <gavinl_at_[hidden]> wrote:
> > 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.)

Yea, I think adding Motivation section will be helpful.

> 
> Quick Starts / Tutorials are more for answering "now that I've already 
> decided to (probably) use this library, how do I do XXX?"
> 
> 
> _______________________________________________
> Boost-users mailing list
> Boost-users_at_[hidden]
> http://lists.boost.org/mailman/listinfo.cgi/boost-users
>