Comment by webprofusion
2 days ago
This is nice, my main criticism would be that it uses the language "easy" and "simple" regularly which is a classic mistake in any instructive text (including docs etc).
If the reader was feeling a bit dumb and/or embarrassed that they didn't yet get the concept being explained then this will only make them feel worse and give up.
Language like that is often used to make things feel approachable and worry-free, but can have the opposite effect.
And never ever, ever write "obvious" in a doc explaining something, because if obviousness was at play they wouldn't be reading your doc.
Excellent point.
I think about wording like that, like the extraneously explicit meta-content that dumbs down so many story plots. A character explicitly says "That makes me angry". When a better written story would make the anger implicitly obvious.
Stories should show not tell.
Make a point, make it clear make it concise, and it will be simple for most readers. Don't talk about making a point, or say a point is clear.
That is projecting attributes or experiences onto readers. But even a very well written point may not appear simple for some readers. Assume (optimistically!) that there will always be some unusually under-prepared but motivated reader. Hooray if you get them! They can handle a challenge every so often.
"Simple" communication is a high priority target, but rarely completely achievable for the total self-selected, beyond intended, audience.
The good ol' "this proof is trivial so we'll skip it" move.
Oh man. The variant I see so infuriatingly often at the moment is “It is clear that these form a Lie algebra/finite abelian group/Hilbert space/bijective map/<whatever other thing that is long-winded or complex to prove> and I encourage the reader to satisfy themselves that this is the case”.
He should have really used the good ol' QED instead, lol