Re: [Boost-users] [range] questions about documentation and usage

Subject: Re: [Boost-users] [range] questions about documentation and usage
From: Neil Groves (neil_at_[hidden])
Date: 2012-11-03 19:10:19

On Sat, Nov 3, 2012 at 11:29 PM, Robert Ramey <ramey_at_[hidden]> wrote:

> Neil Groves wrote:
> > Frankly, I re-read this documentation and its completely obvious
> > whether a type will work with a range algorithm to me. I then got a
> > small sample of developers I know to read it, and none had an issue.
> > If the type is a proper model of the Concept it will work.
>
> I'm not disputing that I'm in the minority here.
>
>
My comment was partly to invite others that have struggled with the same
area to come forward and tell me I'm wrong. They might yet do so.

> > I would hazard a guess that you are finding it hard to determine if a
> > type will work with a range algorithm because you haven't yet got a
> > clear understanding of Concepts and what it means for a type to model
> > a Concept.
>
> I would disagree with this as well - not that it's relevant.
>
>
I put this forward as a hypothesis based on the previous email where you
suggested that it wasn't obvious which types worked with range algorithms.
The types need to be a model of the appropriate concepts. It's as simple as
that from my perspective. Therefore I can only imagine someone that finds
it hard to comprehend which types work with range algorithms having
difficulty with the language used to expression the requirements.

> >  I recommend studying Concepts they formalise generic
> > programming in a manner that makes it easier to reason about complex
> > large-scale generic designs.
>
> Thanks for this advice.

> > The information is correctly stated in
> > the documentation AFAICT and with the appropriate background
> > knowledge I believe it is clear and unambiguous.
>
> Of course this is the crux of our disagreement.
>

Please demonstrate what you would consider an improvement. I think many of
us have tried to obtain something from you to help us. I appreciate that
negative criticism is to some extent useful, but you aren't giving me clear
enough suggestions for positive corrective action. I can't do anything for
you until I understand potential solutions. I accept that my failure to
understand your suggestions may simply be that I'm doing a poor job of
understanding your suggestions.

>
> > The algorithm
> > documentation clearly defines the minimum Range Concept that the
> > template types must model.
>
> I would disagree that it's clear.
>
>
I'm comfortable to disagree with you on this. Boost.Range being largely
Concept-based is a major reason  the library is so general and
interoperable with existing standard Containers and containers from other
libraries. This evidently contributes to usefulness. Perhaps being an early
adopter of Concept-based approaches comes with some learning-curve
disadvantage. I believe the learning-curve is well worth the effort for
using this library, for using other libraries, and for writing your own
libraries. Of course, that's just my opinion.

> > The documentation could always use more
> > examples. I did put these into a separate area in the documentation
> > because I wanted to make them all have tests. The change of layout
> > might not have been optimal and I'll think about this.
>
> I would suggest that each template class/function have a small example.
> The fusion library in particular does this and I've found it very helpful.
> I also suspect it helps detect errors in the documentation.
>
>
That's a good suggestion. I'm happy to try and find time to do this. I'm
also happy to accept your patches to the documentation.

> > Boost.Range has had these Concepts and fundamentally the same
> > documentation about the fundamental aspects of Ranges for many
> > versions. It does not appear to have been a barrier to entry, or
> > caused much confusion among the general Boost user population.
>
> I'm suggesting improvements for those of that aren't so smart.
>
>
I was not suggesting you were less smart. I think it is fair to point out
that your criticism of the documentation is the first of this nature
despite the library being adopted by many. It doesn't make you wrong, but
it is evidence that the documentation is not lacking to the point of making
the library extremely difficult to use. It might be that you have less
experience with Concepts; that is an entirely different suggestion to
suggesting that you aren't as smart. I assume there are a very large number
of subjects where you would understand fundamental material that I am
absolutely clueless about.

> > Boost.Range is heavily designed around Concepts to great advantage.
>
> I'm suggesting that Boost.Range has this wrong.
>

Yes you are, but frustratingly again without any positive suggestive action
which is annoying and unhelpful. I'm trying very hard to comprehend your
issues and I've asked previously for you to put forward something
constructive. I think this would help me comprehend your points. It's
perhaps harder for me to see deficiencies in the documentation that any
random person since I've been so immersed in the library for so long. I'm
perhaps simply assuming something, but I require more constructive feedback
to understand the issue you having and the solution you are proposing.
Where you have provided positive suggestions such as increased examples I
have immediately been able to understand and put this onto my todo list.

>
> > It is therefore inherently necessary to comprehend Concepts to
> > understand Boost.Range.
>
> I don't believe that it is necessary for users to comprehend Concepts
> to use a library.  Definitely helpful - but not necessary.  I personally
> find it helpful - that is why I carefully read the documentation concerning
> them - and found the documentation misleading and in need of improvement.
>
> > The only thing I can think of doing to the documentation to address
> > this is to perhaps make more clear the importance of understanding
> > Concepts.
>
> To whom?
>
>
To the readers. Many documents / papers I read have a better enumeration of
the pre-requisite subject matter that is expected to be understood as
foundational material. I was trying to find actions to make the
documentation better. I wondered if this might help address your concerns.
However your response shows that I have misunderstood the source of your
confusion anyhow, so this isn't a valid solution.

> Robert Ramey
>

Regards,
Neil Groves