Re: [boost] [Boost-users] [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 <gavinl@compacsort.com> 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
Le 09/03/2016 08:36, paul Fultz a écrit :
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 <gavinl@compacsort.com> 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.
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
participants (2)
-
paul Fultz -
Vicente J. Botet Escriba