[boost] Re: Changes with new release

From: David Abrahams (dave_at_[hidden])
Date: 2003-07-22 10:05:41

"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?

>>  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.

>> That said, I thought you were asking for something else, and I
>> probably overreacted a bit: I'd been up all night and my nerves were a
>> bit frayed.
>
> OK, I am not out to create more work needlessly for developers and I
> am not targeting any individual here in my remarks. Encouraging
> programmers to document what they are doing better shouldn't be
> something which generates such antipathy 

As I've already said, it's not the suggestion to generate more
documentation which generates antipathy... at least not over here.
It's the "other stuff".

> simply because many programmers see it as unnecessary and needless
> effort. 

Most Boost developers clearly recognize the importance of
documentation, a fact which should be obvious from looking at the
Boost site.

> I do not know how to explain it better but I think that the
> ability of programmers to explain their ideas and thinking clearly
> is of great importance, not only for them but for the users of their
> software. 

Agreed.

> My remark was just a suggestion, not an attempt to establish a
> rule. But if it leads to having library implementors documenting the
> major changes that occur in their library from release to release, I
> think it will do an important service to the many users of those
> Boost libraries in the C++ community.

It's a good suggestion, as I mentioned above.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com