I think there are two "axes" here: One is: - A: a list of functions or similar items, vs - B: a description of a model, its operations, and terminology The

I think there are two "axes" here: One is: - A: a list of functions or similar items, vs - B: a description of a model, its operations, and terminology The other is - X: "the only job is to describe, as clearly and completely as possible", vs - Y: "a chance to relax and step back" My reading of the "what nobody tells you" article is that it envisages a reference which is A and X, and an explanation which is B and Y. I recommend that the reference should be A, B, and X. Having an explanation which is B and Y is a fine thing too. So basically the bit I don't like in that article is where it says the reference should not attempt to explain basic concepts. Maybe it doesn't need to try to teach concepts, but it very often does need to define them. (Also, I think rationale fits well in the "describe as clearly and completely as possible" document, especially if you're in a position to separate it a bit from the main text.)