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

Subject: Re: [boost] [Boost-users] [Fit] formal review starts today
From: Vicente J. Botet Escriba (vicente.botet_at_[hidden])
Date: 2016-03-09 02:48:32

Le 09/03/2016 08:36, paul Fultz a écrit :
>
>
>
>
>> 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.
Paul, I believe it will be worth trying to replay on these threads with 
whatever you believe you would add to the documentation. In this 
particular case we would like to have the motivation.

If we want to be able to accept the library we need responses, if you 
give only promises we would only restart the review only once we have 
this information.

So what is the motivation of the library, what the user can do with that 
can not do already? Why those are good use cases?

Vicente