Computer science concepts can be difficult to explain due to their abstract nature. Programs serve as useful demonstration of these concepts, as the program running and producing the correct output is an extremely simple way to verify the validity of a claim.
Unfortunately many forms of educational content, including textbooks, papers, and framework/module documentation, stop at this point in the education process.
Code is the end, not the means
Code is the best tool we have for conveying programming ideas to computers, but it's not at all the best tool for conveying these ideas to humans. Animations, illustrations, and tactile demonstrations help cement new ideas with much more clarity than code examples.
It's extremely difficult to understand code that implements a concept you don't understand. The problem with using code to teach a concept is that you're attempting to teach both the concept and an implementation of the concept in the same step.
An analogy
Imagine a student musician playing a Db major scale in the context of a piece. If the student has practiced this scale before, they have a higher chance of recognizing the notes in the piece as "just a Db major scale" and using their previous practice and experience to perform accurately.
(Credit: BasicMusicTheory)
In contrast, if the student had never played the scale before, there are two things likely to occur when they come across the scale in the piece:
- They will not recognize that the progression of notes form the scale
- They will most likely not perform the notes accurately
Thus a band director or private instructor would find it wise to have the student practice the scale in isolation before attempting the piece.
How this relates
With the tendency to explain concepts within code, we are asking other programmers to perform a scale they've never seen in the context of a piece. The code sample will only make sense if the concept is understood, so we place double the cognitive workload on those we are attempting to educate.
Examples of CS Concepts explained outside of code
The Bubble sort folk dance
Introduction to recursion
Apply these examples outside of computer science!
If you author a non-trivial module or framework, educating your potential users has tremendous advantages. If your documentation educates as opposed to merely providing code samples, your users are more likely to make good decisions and perform well when working on their projects. This is because they will understand the nature of your code and the types of problems it can solve. If people perform well on their projects due to your project, word-of-mouth will bring more people to use it!