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

From: Brian Braatz (brianb_at_[hidden])
Date: 2005-06-07 11:39:00

> -----Original Message-----
> From: boost-bounces_at_[hidden]
[mailto:boost-bounces_at_[hidden]]
> On Behalf Of Jody Hagins
> Sent: Tuesday, June 07, 2005 8:49 AM
> To: boost_at_[hidden]
> Subject: Re: [boost] Re: [function types] Formal Review begins today.
> 
> 
> > 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.