Boost logo

Boost :

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
>


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk