[boost] Re: Changes with new release

From: Edward Diener (eddielee_at_[hidden])
Date: 2003-07-22 12:30:13

David Abrahams wrote:
> "Edward Diener" <eddielee_at_[hidden]> writes:
>
>> David Abrahams wrote:
>>> "Edward Diener" <eddielee_at_[hidden]> writes:
>>>
>>>> David Abrahams wrote:
>>>>> "Edward Diener" <eddielee_at_[hidden]> writes:
>>>>>
>>>> I am always surprised when programmers, such as yourself in this
>>>> instance, react so vehemently to those who suggest that
>>>> documentation can be better in any respect. I don't think of
>>>> writing documentation as easy, and I am sure my own is as flawed
>>>> as much other documentation is, but the merest suggestion to
>>>> improve documentation standards for programmers always meets with
>>>> a similar response which you have given here.
>>>
>>> Not from me.  I'm always one for better documentation, and you'll
>>> note that I instituted just such a changelog for Boost.Python not
>>> long ago; it's a good idea.  What I was reacting to was the
>>> insulting suggestion that library authors who don't publish the
>>> ChangeLog you want are poorly educated.
>>
>> I didn't say that at all and I do not think it is reasonable in any
>> way to infer that from my remarks.
>
> I think:
>
>     "I have never quite understand why so many good, and often
>     brilliant programmers, take it so hard when others suggest that
>     they document what they do in easily understandable
>     sentences. There must be something wrong in the educational
>     systems of the countries from which most programmers come when
>     they can not, or do not, want to write clearly."
>
> speaks for itself.  If you meant something else by that remark,
> perhaps you'd like to clarify?

You have no doubt read something into a general remark which I did not
intend. Clearly that was not targeted to "library authors who don't publish
the ChangeLog" or I would have been much more specific about it. Nor do I
accuse anyone of being poorly educated.

I am critical, again in general, about the unwillingness of many programmers
to want to communicate their ideas in clear and cogent prose, and about
educational systems, in general, that do not feel it is their responsibility
to educate students so that basic writing proficiency is met. But that is my
right in a free society, to think for myself and have my own opinions and
beliefs about those things.

I still do not understand the brouhaha which is often caused when someone
suggests that things be documented as a help to other programmers. When
someone says that an implementation might be improved by changing something
in some way, programmers discuss this rationally and reasonably in most
cases, usually no matter how assertive people are in their suggestions as
long as it remains a technical issue. When someone suggests, let's have
better documentation of something, programmers get very defensive in most
cases and hostile in some others. It appears to be sacrosanct ground one is
treading upon when one seeks to improve things in the programming world by
encouraging better documentation, and argues for that improvement even in a
low-key way.

>
>>>  This is hardly first time we've been over this
>>> ground:
>>>
>>>   http://lists.boost.org/MailArchives/boost/msg38799.php
>>>   http://lists.boost.org/MailArchives/boost/msg38801.php
>>>   http://article.gmane.org/gmane.comp.lib.boost.devel/11576
>>
>> These are irrelevant to the present post.
>
> Except that I'll be much more likely to "react vehemently" to posts I
> perceive as aggressive if there's a history of similar offensive
> behavior behind it.

I don't see offensive behavior in those posts. That's not a fair way of
criticizing positions with which someone doesn't agree, by calling it
offensive. But even if you do really feel it is offensive by your standards,
past interpretations of actions should not be used to view judge present
situations.

We are getting nowhere in this discussion, however, and I don't think we are
really disagreeing with each other. I can only attest that my remarks were
meant to encourage Boost programmers to better document changes in their
libraries so that users could better understand how each new release affects
their own programming endeavors with Boost.