[boost] Re: Changes with new release

From: David Abrahams (dave_at_[hidden])
Date: 2003-07-22 07:17:48

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

> David Abrahams wrote:
>> "Edward Diener" <eddielee_at_[hidden]> writes:
>>
>>> Actually I am quite serious with my preceding paragraph. 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. Yet many of the Boost implementors do write well when
>>> they attempt to do so.
>>
>> Maybe you should try writing a library as a volunteer sometime and see
>> what happens to your standards for others' work.
>
> I have written a library but not a Boost library (
> http://www.tropicsoft.com/Components/RegularExpression ).
>
> 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.  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

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

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