Re: [boost] Re: Re: Property_map docs

From: David Abrahams (dave_at_[hidden])
Date: 2002-11-12 08:55:17

"Edward Diener" <eddielee_at_[hidden]> writes:

> I didn't "demand" anything. Criticizing what I believe to be inadequate
> documentation is not a "demand". If programmers can't ask for better
> technology, and make criticisms accordingly, then we are all in a great deal
> of trouble professionally. 

I agree with that. Your last major post was almost a step forward in
this direction, until the last 2 paragraphs...

> Improving technology can not be done by pussyfooting around with
> endless awe and respect in our eyes. 

Endless awe? No, that's unproductive. Endless respect? Yes, I think we
should all aspire to that.

I'm going to try one last time to make this work out, because I think
that however belligerent, insulting, and disrespectful he may be, when
it comes to documentation, the user is always right. There's probably
something that could be done better in the library docs.

However, as you can see from Jeremy's reaction, it's important how you
approach people, especially those with good intentions, when
requesting changes and improvements. In particular, this text:

    "Rather than explain how to use your concept in detail to do
    generic programming, you want to insist that you have explained it
    adequately for other implementors to use it and that is what
    matters to you. "

Jeremy never said he was targeting library implementors, and he never
implied that they were the only audience that mattered to him. Given
what I know to be his very real desire to serve users, this is
insulting.

    OK, I will move on. I find it useless to fight with those who feel
    that the documentation is only for others "in the know" and not
    for the uninitiated.

_You_ are the one who keeps insisting that Jeremy only wants to serve
those "in the know". I don't think there's a single Boost contributor
who feels that way about documentation. The only explanation I can
think of for your response is that the documentation made you feel
stupid somehow.

    I see universities connected with your name. Having gone to
    colleges myself many moons ago, I find it unbelievable that any
    college would accept your documentation as adequate explanation of
    your concept. Either colleges have deteriorated from what they
    were when I went there, or you don't perceive the need for the
    same amount of professionalism in dealing with other programmers
    as you would in dealing with college standards.

And this part is just a completely gratuitous attack. Jeremy responded
to you graciously and courteously, despite your initially belligerent
tone. He clearly doesn't see why you had trouble with his
documentation, but that should be cause for more patient explanation
on your part, not this.

> I have yet to see a valid argument against the suggestions and
> criticisms I posted. The doc is poor, but if everyone agrees it is
> good enough and understandable to them, fine and so be it.
>
> I am appreciative of many, if not almost all, of the fine ideas and
> implementations in the Boost libraries. Is it uncriticizable because
> it is freely done ? Sometimes criticism is needed to improve
> technology, and when that happens we are all winners.

And when you "come out swinging" instead of trying to work with
people, they eventually get hurt and are unwilling to listen any
more. At that point, we're all losers. Human nature, you can't beat
it.

-- 
                       David Abrahams
   dave_at_[hidden] * http://www.boost-consulting.com
Boost support, enhancements, training, and commercial distribution