David Abrahams wrote:

"Brian Braatz" <brianb@rmtg.com> 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-).