webprofusion
3 hours 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.
Nevermark
an hour ago
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.