[boost] Re: Changes with new release

From: David Abrahams (dave_at_[hidden])
Date: 2003-07-20 20:45:22

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

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