Boost logo

Boost :

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

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

Boost list run by bdawes at, gregod at, cpdaniel at, john at