-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Jody Hagins Sent: Tuesday, June 07, 2005 8:49 AM To: boost@lists.boost.org 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.