How to write a fantastic book in four months, Part II
In the second post of this series about Relational Thinking: from abstractions to applications, we look at the technologies used to build the book.
Welcome to the second post of this series! At Topos we recently completed an online book on Relational thinking (a.k.a. category theory). We introduced this book in our previous post. In this project, we experimented with a few open source technologies and made a few non-traditional design decisions to make the book inclusive. This post is about these technologies and how it supported our design decisions. Probably, we could think together what other affordances one would wish for!
The two main design decisions we took early-on in this project are:
- To enable the users to experience the capabilities of AlgebraicJulia without having to learn coding;
- To bring category theory and mathematical thinking to the reader without wanting the reader to have a formal mathematical training.
The above were hard to implement decisions given the time-frame of four months. But, with the right sort of technologies and people to support these decisions, we got the ball rolling!
We are grateful that the team included Paul Dancstep, an excellent illustrator who is also an avid fan of Category theory (but not its textbooks).
Paul’s illustrations did lots of heavy lifting regarding the second design decision. But, we needed technologies that would support multimedia as well as coding. Luckily, we found good open source technologies that could communicate with each other to support what we were looking for! Here is a brief overview of these technologies, and our experience in setting them up.
Technology 1: Jupyter Book, the infrastructure of the book
The book is built on the platform of JupyterBook which is an environment to “build publication-quality books and documents from computational content”. Setting up this environment and connecting it to GitHub was quite easy. We just followed the tutorial provided on their website.
JupyterBook supports markdown and its special flavor myST markdown. When the book is compiled locally, it will generate a link to view the book locally in a browser. The book can also be published on GitHub pages or on Netlify quite easily. This means we will have a public URL to view the book like this one. We have automated the workflow to deploy the book on the Github pages from the master branch after each push. All the configuration of the book is set up in _config.yml.
Our experience with JupyterBook was quite smooth.
Technology 2: Binder, the computing environment of the code
Binder is an open-source computing environment for Python, R, and Julia. Binder provides a sandbox with about 2GB of RAM in their server for anyone to run their JupyterBooks. Each time the binder is invoked, it will automatically install the kernel for the user. Our guess is that the sandbox is held active for a few days before it is deleted from the server. Given that Julia and its packages are resource-heavy, the installation took several minutes until ready.
We frequently found ourselves overshooting the memory limit. So we had to move the code of Chapter 2 outside the live coding environment of the book and make the code available separately in Github for the readers to try it out in their own machine.
Configuring Binder with JupyterBook is very simple and a one-liner.
Balancing our requirements of a computing environment with what Binder offers was quite a task! We are glad it all worked in the end! From our understanding, Binder works quite well with Python and R. With Julia, we still had to figure out things with support from their community.
Nevertheless, what Binder offers free of cost is already quite generous, and their community is very welcoming! It was a little hard to believe in the beginning that this service is free.
Technology 3: Thebe, the live coding and execution in HTML pages
With Thebe connected to Binder, we can execute code in our JupyterBook. This is a screenshot from Chapter 5 of our book demonstrating this feature. The code can be edited/run on the fly.
Adding Thebe to the JupyterBook configuration enables this feature. The Thebe configuration will also tell the Binder what kernel to install in the sandbox. The greatest difficulty we had was with specifying the right kernel name (julia-1.10) which binder can identify.
Otherwise, Thebe is quite easy to use! We tried it standalone without JupyterBook and it was quite easy to get it going!
Technology 4: Javis, the Julia library for animations
Finally, this is a software we used to animate a few results of our code. This is not part of the book infrastructure. But, it is a standalone tool which we used in Chapter 2 as a support for our story-telling form of writing. Here’s an example animation that Javis created from the output generated from the code simulating a traffic light as a dynamical system:
That sort of completes the tour of the main technologies used in this book. Most of the illustrations were done in Cinema 4D and After Effects. We also used Canva for making simple banners, colorful collages, and to design the cover of the book.
We quite liked the result of it all. We hope the book inspires you too to write and to experiment with these new technologies!
- Github repo of the book: github.com/ToposInstitute/AlgJulia-Book
- Github repo of the code: github.com/ToposInstitute/RelationalThinking-code
What more can we ask for from technology?
It may be helpful for the readers to have a discussion / commenting feature at the end of each chapter. Right now, we redirect our readers to the Category Theory Zulip and LocalCharts.
It will be helpful to have cross-referencing content blocks within the book. This feature is available but we could not get it working for the book. (The new version of the JupyterBook has a search feature!)
Community support. We are grateful to both the Julia and JupyterBook communities for their prompt guidance when we were stuck.
Acknowledgements. Thank you Evan Patterson for introducing Thebe early on to our team, which led to working with JupyterBook.