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

From: David Abrahams (dave_at_[hidden])
Date: 2005-06-07 12:56:33

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

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