[boost] Re: Changes with new release

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

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.

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

>
>>>  It is difficult and time-consuming enough to write coherent
>>> user-level documentation as required by Boost that IMO it's
>>> unreasonable to demand implmentation documentation at the same
>>> level.
>>
>> All I asked for is that when changes were made between releases to a
>> library a small amount of documentation be given which elucidates
>> what those changes were in a general way. It would help both users
>> of a Boost library and 3rd party developers of a Boost library, as
>> it would enable both parties to track general changes and adapt
>> their understanding of the library from within their own code to
>> those changes.
>
> 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 simply because many programmers see it as unnecessary and
needless effort. 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. 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.