Learning : Teaching : Architecture of Explanations
- 1 Explanation by Difference/Comparison
- 2 Reference Avoidance
- 3 All Designations must have Exactly one Meaning and all Designated Objects must Always have Exactly one Designation
- 4 Whenever Possible, Succinct Duplication of new Definitions Should be Added to the text, Chapters, that Immediately Follow the First Occurrence of the new Definitions
- 5 Sub-optimal code and Naive Algorithms can be used as Documentation for Heavily Optimized Implementations
Explanation by Difference/Comparison
First, describe something that the audience already knows well, and then explain, how the new concept differs from the previously known concept.
If a target of a reference can be said succinctly without oversimplification, then in stead of saying, "According to the paragraph/section/theorem XYZ", the theorem/section/paragraph should be cited. This avoids the attention shift that occurs during the studying of the reference.
This rule should be ignored, if it is likely that the audience already knows the reference by heart.
All Designations must have Exactly one Meaning and all Designated Objects must Always have Exactly one Designation
This rule is usable only within a limited scope. Context sets some of the limits to the scope and designations. For example, the physicists use the letter "f" for frequency, which means that in physics texts "f" should not be used for designating mass or speed.
Whenever Possible, Succinct Duplication of new Definitions Should be Added to the text, Chapters, that Immediately Follow the First Occurrence of the new Definitions
It takes repetition to remember. It's hard to understand sentences and mathematical explanations that contain words, definitions that are not known to the reader. Hints, preferably succinct forms of full definitions, should be added to the text that immediately follows the first occurrence of the definition. It might also be that the reader misunderstood some aspects of the original definition, in which case the different wording of the definition might help the reader to detect the misunderstanding.
Sub-optimal code and Naive Algorithms can be used as Documentation for Heavily Optimized Implementations
A citation of Niklaus Wirth:"I've found that it is hard to program correctly, but it is much harder even to program in such a way that You can publish, that the program is so concise and so much rid of unnecessary details that other can understand it relatively easily and learn from it."
Another idea in the same vein is that source code can be analyzed and run by some heavily verifying interpreter or compiled by some heavily verifying compiler and then analysed on multiple, different, kind of implementations and after finding the flaws the deployables can be compiled by some heavily optimizing compiler. The heavily optimizing compiler might introduce flaws of its own during the translation, but at least the initial code has been debugged thoroughly. Algorithm development has its own chapter.