[boost] Re: Changes with new release

From: Edward Diener (eddielee_at_[hidden])
Date: 2003-07-21 22:31:25

David Abrahams wrote:
> "Edward Diener" <eddielee_at_[hidden]> writes:
>
>>> Not hard, no, but it certainly takes more time than it might appear.
>>> FWIW, I've started such a section for dynamic_bitset. The doc file,
>>> for now, is in the boost sandbox, subfolder /libs/dynamic_bitset.
>>
>> I am glad to see you doing that. I still don't understand all the
>> pain that many others seem to feel in documenting what they are
>> doing.
>>
>>>
>>>> If I were a
>>>> library implementor, whether Boost or otherwise, I would want to
>>>> explain my ideas to the outside world as a way of promoting good
>>>> technology.
>>>
>>> Ahehm... :-)
>>
>> An extra 'h' maybe <g>. Or is it just extra phlegm that got stuck in
>> your throat when you typed it <g><g>.
>>
>> 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.

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