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
>>>> 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
>>> 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 (
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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk