Skip to main content

Theories of Learning applied to documentation

· 4 min read
zach wick

Modern computers, or rather the computer programming languages that control them, are Turing-complete. This means that computers as we understand and experience them today can solve any problem whose solution can be solved by an algorithm. Because any two Turing-complete systems can simulate each other (this is called equivalence), there exists more than one way to solve a given problem using a computer (or any other kind of Turing-complete system). This necessitates that when learning how to use a computer to solve a problem, the human involved in that decision-making must use a constructivist point-of-view to evaluate the computer-aided solution. That is to say, using a computer to solve a problem is more like building a bridge out of local stone whose design is inspired by previous stone bridges that the architect has experienced; it is not like uncovering a universal truth as in Michelangelo's description of revealing the statue that was already within the block of stone:

“The sculpture is already complete within the marble block, before I start my work. It is already there, I just have to chisel away the superfluous material.”

The educational process of learning computer programming, which is the same as learning how to evaluate if the computer-aided solution to a problem is sufficiently correct or not, requires practice making similarly shaped evaluations in a wide variety of contexts to develop a sense of what constitutes a faithful representation of the problem to be solved and its proposed programming solution. This is similar to the idea of finding success by getting lots of shots on goal. Phrased another way, educational experiences are best for the learners when tools and methods are evaluated on a per-learner basis instead of just assuming that if a given educational experience works for one learner then it will work for all learners.

To encourage learners to practice these skills in ways that grow in complexity proportionally to their skills and experience, tools can be specifically selected that lend themselves nicely to this process. For example, there exists a programming language called APL, which began as a set of handwritten notation to help learners express algorithmic solutions to problems in an abstracted way. The notation of APL lends itself well to the mathematics of arrays, and because of how exactly its notational language can be composed (via grammar rules as in any other language), APL also serves as a powerful computer programming language. It is particularly well suited to the task of teaching computer science concepts to new learners using the language of basic arithmetic and elementary array manipulations. In fact, APL was created as an abstraction of the existing mathematical notation for these areas to facilitate exactly this constructivist style of learning by applying existing knowledge from one field of study to a new field in order for learning to occur.

When applied to documentation, the takeaway is to present the same content in a variety of ways to increase the likelihood of a learner finding the documentation useful. The easy trap is to churn out a laundry list of cookie-cutter-shaped retellings in different media formats - screencasts that are simply readings of blog posts, live talks that are just live versions of the screencasts, and so on. Instead, take advantage of the unique features of each medium to enhance the material. For screencast-shaped documentation, this means longform content that shows a worked example of a real-world problem that a user can solve using the product. For live talks, real-time interactivity is the main unique feature.

As always, the message of any communication must be tailored to its audience. However, the medium of the message acts as the limiting reagent for the act of tailoring the message to its audience, and so to optimize for the impact of documentation is to carefully choose the least limiting reagent for the intended audience.