The biggest mistake in teaching is not providing enough context.
So often teaching (or documentation) devolves into mere description. As if detailing every part of an automobile is a good way of teaching how one works. The human brain is a wondrous thing, so even with such a horrible method of teaching eventually smart people will pick things up. But it's a very inefficient and error prone method.
The right way to teach is to start with an abstract, low-fidelity model and then build upon that. Once students have a good mastery of the model then you can delve down into fine-grained specifics (how each component works, for example) and only then can you evolve the model into a more accurate representation.
That's why good teachers are so rare. Because it's easy to "teach" a complex system by describing each component in detail, but it's harder to come up with a series of models from low-fidelity to high-fidelity that bootstrap up from zero knowledge to expertise.
So often teaching (or documentation) devolves into mere description. As if detailing every part of an automobile is a good way of teaching how one works. The human brain is a wondrous thing, so even with such a horrible method of teaching eventually smart people will pick things up. But it's a very inefficient and error prone method.
The right way to teach is to start with an abstract, low-fidelity model and then build upon that. Once students have a good mastery of the model then you can delve down into fine-grained specifics (how each component works, for example) and only then can you evolve the model into a more accurate representation.
That's why good teachers are so rare. Because it's easy to "teach" a complex system by describing each component in detail, but it's harder to come up with a series of models from low-fidelity to high-fidelity that bootstrap up from zero knowledge to expertise.