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

...

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,

On Tuesday, March 8, 2016 11:39 PM, Gavin Lambert wrote: 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@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users