Site icon Tim Cason

How Literate Programming Could Change Your Life


And Why Every Programmer Should Learn Observable

And now for something completely different*… BREAKOUT!

How did you do? Did you win the game or lose immediately? Did you expect a game when you first opened the post?

TL;DR: Too Long Didn’t Read

Software is written for other programmers to understand. Data should be written for everyone. Literate programming reduces surprise with well communicated documentation.

Shifting from the Unknown to Navigating Expectations

What if you knew you were going to play a game when you clicked the article? Would you react differently? HINT – You can always refresh the page and play again, this time with the idea of what is to come. My guess is that you do much better the next time.

The random, extreme events that we cannot predict are known as Black Swan events, as coined by the essayist, Nassim Nicholas Taleb[1]. While a BREAKOUT! game appearing doesn’t quite qualify as a Black Swan event, I wanted to emphasize the point about awareness and expectations.

Perhaps, if the post was titled, “How I Followed a Tutorial and Built the Game Breakout! [2]”. With a little more information, you would have been prepared to play Breakout! No matter how large or small, any amount of “priming” can lead to a better outcome.

What’s “Literate Programming” Got to Do with It?

What is Literate Programming?

Literate programming is writing out the program logic in a human language with included (separated by a primitive markup) code snippets and macros. [3].

Simply put: You should explain what you did in HUMAN language. What a concept, right? 🤦‍♂️ Write notes on how you got to the answer to help walk the reader through the process, step-by-step. And though, it’s been 15 years I finally get why my Pre-calculus teacher Mr. Bouknecht stressed the importance of showing my work.

Systems of Development

In fact, in software development, we have a way of conceptual priming and ‘showing our work’. We do this through Commenting Code. A programmer will write “Human (Readable) Language” around the running code that explains the how-to’s of a specific function, source, or choice.

From my experience there are (3) three stages that a programmer goes through while commenting their code.

  • 1st Stage – A new developer hasn’t learned that good development is driven by writing your comments first, so they don’t comment their code at all.
  • 2nd Stage – They comment their code and it helps them walk through the logical steps of solving a problem, but their code isn’t easy for another programmer to read.
  • 3rd Stage – Their problem solving competency doesn’t require them to write comments and the code they deliver is clean and self-explanatory.

As Jeff Atwood explains[4]:

… write your code to be consumed by other programmers first, and by the compiler second…

What is this About Observable?

Observable is the platform where “Human Language” can frame up code AND data. It will show how a specific result was achieved. The environment is a cellular, where the code can be executed line-by-line and data visualization can be achieved with a few imports of core code libraries.

For most developers, this probably doesn’t feel like a huge leap. However, the methodology of Literate Programming can bridge the gap of complex ideas and problems that need to be solved.

So How Could Literate Programming Change Your life?

  • You will be able to communicate code strategies and implementation to non-technical people which allows for better time and resource allocation
  • Since programmers are front-line experts on software infrastructural issues, scope creep, they could explain impending 0-day or server crashes [see COBOL Programmers for Unemployment Office]
  • Be able to communicate complex data in a simple form
  • You will create a record of solving complex problems, technical or not, without having to second-guess how you arrived at your conclusion
  • Reduces the probability of Black Swan events by communicating data that helps to drive support for cause

Why Should Every Programmer Learn Observable?

  • Reduce the complexity of problems through communication
  • Enlist and on-board the assistance of others for increase brain-power on a single problem

Software is written for other programmers first. Data should be written for everyone to understand. Communicating ideas and implementation will allow for greater capacity to collaborate, understand, and solve complex problems. Literate Programming enacts conceptual priming to bridge the gap between software development and non-technical problem solvers by explaining each step in a given solution. Observable is a platform for such collaboration and geared for illumination of information using data visualization.



  1. Taleb, Nassim Nicholas. “OLDER SEQUENCE.” Opacity: What We Do Not See – A Philosophical Notebook, Self-Published,
  2. Cason, Timothy. “Breakout! Game.” Observable, Observable, 20 Apr. 2020,
  3. “Literate Programming – Concept.” Wikipedia, Wikimedia Foundation, 5 Apr. 2020,
  4. Atwood, Jeff. “Code Tells You How, Comments Tell You Why.” Coding Horror, Coding Horror, 19 May 2016,

Originally posted 2020-04-20 09:47:22.

Exit mobile version