This is a great time to be an author. It is easier than ever to produce content that actively involves the reader. In this article, I give a few examples and discuss what I learned about creating interactive materials.

The Script is Mightier...

The pen may be mightier than the sword, but in the end, all it can produce is static text. These days, when I write something, I often want to involve the reader.

Example 1

My introductory computer science textbooks have interactive elements such as this demonstration of the algorithm for finding the largest element in an array:

Here is another example, a code tracer:

int n = 1729;
int sum = 0;
while (n > 0)
   int digit = n % 10;
   sum = sum + digit;
   n = n / 10;
n sum digit

These elements have been hugely popular with students and professors.

Example 2

Marc Hoffmann and myself are writing a series of articles on new Java features at http://javaalmanac.io. Marc wrote a nifty tool that compiles and runs code samples. Readers can run the code and see for themselves. More importantly, they are invited to tinker with the code and observe the effect of their tinkering.

public class InstanceofDemo { public static void main(String[] args) { Object what = Math.random() < 0.5 ? Math.random() < 0.5 ? 42 : -42 : "1729"; if (!(what instanceof Integer i) || i.intValue() <= 0) { System.out.println("No good: " + what + " is not an integer or not positive"); } else { System.out.println("Hooray: a positive integer with value " + i.intValue()); } } }

Example 3

I felt the urge to write up some tidbits about plane geometry that I discovered while helping my daughter with her math during the COVID-19 lockdown. I needed figures. Sure, I could have drawn them myself with Inkscape (major time sink), Geogebra (not easy to customize appearance) or this amazing tool. Instead, in a few hours, whipped up some JavaScript to draw points, lines, and circles. Here is one figure:

You can drag the blue points, which gives a bit of insight into the construction. It is much better than a static picture for another reason. My original instinct was to draw one picture, cramming all the details into it. But with the JavaScript element, it was trivial to add and remove pieces of the drawing, and I produced a much more informative sequence of five drawings. Check it out.

Advice from the Trenches

If you write to teach something to someone, you can now involve the reader like you never could before. Here are some tips:

  1. Write in HTML or use Markdown/ASCIIDoc to generate HTML. Publish on the web or, if you want to sell your writing, use EPUB3. (EPUB3 is just zipped XHTML, CSS, and JavaScript with a small amount of metadata.)
  2. Don't be afraid to write some JavaScript. It doesn't take many lines of code to create fairly impressive effects. For example, the plane geometry element has just over 300 lines of code.
  3. Design your elements with reuse in mind. In my textbook, I have hundreds of interactive elements, using only a few templates.
  4. Use HTML, CSS, and SVG, not Canvas. You get scaling for free, and CSS can do all sorts of fancy rendering with little coding effort. For example, the moving paperclip in the code tracer is done with a trivial style rule.
  5. Plain JavaScript is fine. There is no need to learn Angular/React/Vue if you don't want to. You can go a long way with just a few DOM calls (creating/adding/removing nodes, changing attributes and styles, listening to clicks and drags).
  6. You don't need to know a lot of JavaScript either. Everything in the elements that I wrote is covered in Chapters 1 - 3 of Modern JavaScript for the Impatient. (That's the book that I just completed, and that I wish I had when I started my involuntary journey into JavaScript.)
  7. If your activity needs to do work on the server, such as code evaluation, that's nowadays pretty easy too, with a VM or Docker container at your favorite cloud provider.
  8. Unfortunately, communicating with a learning management system is not yet easy. This is a problem for textbooks and courseware, whose adopters want to make sure that their students actually do the activities. The EPUB for Education draft has a proposed API for interacting with a host system that can then interact with a learning management system, but I only know of one implementor—VitalSource. If you need to do this, contact me. I am working on an open source solution.

Comments powered by Talkyard.