Boost logo

Boost :

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
>>[Jody Hagins Writes:]
>>[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-).

Boost list run by bdawes at, gregod at, cpdaniel at, john at