[boost] Re: [function types] Formal Review begins today.

From: Tobias Schwinger (tschwinger_at_[hidden])
Date: 2005-06-07 17:13:09

David Abrahams wrote:
> "Brian Braatz" <brianb_at_[hidden]> writes:
> 
> 
>>>>Seems like we have a fundamentally different taste when it comes to
>>>>documentation...
>>
>>[Jody Hagins  Writes:] 
>>
>>>Probably.
>>>
>>
>>[Brian Braatz Writes:] 
>>Allow me to suggest 2 ways of thinking about library documentation:
>>
>>1- The better the documentation is, and the more it speaks to the
>>average user, the more usage the library will have. If the docs don't
>>make sense, people will SKIP using the lib. (which is a shame)
>>
>>2- The lower the skills required of the reader the better. I realize one
>>can only do so much in documentation. I am simply stating that the
>>simpler and more understandable the docs are the better. This is because
>>the "skilled" folks can skip the intro if it is obvious.
>>
>>I believe:
>>
>>"Brilliance is a mastery of the obvious" <*>>> and documentation should
>>seek to brilliantly expose the obvious over complicated subjects. 
> 
> 
> Another thing: the author of documentation should (usually) disqualify
> him- or herself from making judgements about understandability and
> especially approachability.  The problem is that once you understand
> it, it's very hard to see the places where it fails to communicate to
> someone who doesn't.
> 

However, (in this particular case) the author believes that taking a rather 
conservative position has helped pinpointing the passages that need improvement.

Further, he seriously doubts that the purpose of this thread is designing new 
t-shirts 8-).