Structuring Technical Blog Posts
Recent discussions with colleagues and friends have me thinking a bit about the writing process, and how to structure technical exposition. I am one of those weird people who just sits down and starts writing when I have an idea, but over the years I have ended up building a few formulas, loosely speaking, for technical blog posts.
In the interest of inspiring more writing, here are a few of the structures I have used.
Explaining to myself
This one is pretty self explanatory: I write an article that explains a topic to my former self at some point in history. This one works well for isolated articles because you can assume any amount of prior knowledge you'd like. It can be yourself from two weeks ago, knowing most of what you know now but unaware of some key insight. Or it could be to yourself from two years ago before you took some course, read some book, or started and finished some large project.
This advice is a bit trite. If you read about writing, you have probably heard William Zissner's quote from "On Writing Well," which goes something like "you are writing for yourself." In Zissner's case it was more like, you are writing about things that speak to you and excite you, and if you do it genuinely it will excite other people, too. But with technical writing there's more to it. What confused you almost certainly confuses others. There have been so many times in my life when a single sentence or shift in perspective has illuminated an entire topic. What confounded and frustrated you is among the best material for technical writing, especially if you overcame the obstacles and found a new insight.
This kind of article often focuses on a single nagging question, like explaining the meaning behind a jargon-laden sentence or starting from a naive (or wrong) understanding of a topic and working to correct it. A good sub-section to include in such an article is the "if I went down this a-priori-reasonable path, where would I get stuck or fail?" In math in particular, dead ends are almost never described in detail.
Some good examples of this in my old writing includes "How to Conquer Tensorphobia", "Elliptic Curves as Algebraic Structures". Though I did less of the "follow the wrong path on purpose" recipe in those articles, I have been doing it more recently and finding it works exceptionally well.
The touchstone example
This can be mixed with other formulas, but the idea here is to explore a topic through the lens of a touchstone example. The example should be representative of the point you're trying to make, either by being a particularly good counterexample to some naive reasoning, or else demonstrative of some realistic data one expects to encounter in the real world.
For instance, you might be studying graph theory, and demonstrate every definition and theorem in terms of the Petersen graph, a graph so notorious that math lore insists you have to test every conjecture on it first, since it's the most likely to provide a counterexample. Or, if you're studying graphs in order to motivate something like dependency resolution, you can come up with a (hopefully small) dependency graph that demonstrates the key obstacles to dependency solving, and use that to show how different algorithms work. In this applied setting, the touchstone example is a carrot to keep a reader interested, especially if that reader might struggle to keep up with dense technical content. Put simply, the best way to demonstrate a definition of theorem is to show an example that truly needs it.
For example, in my series on groups, modular integers are the touchstone example (and, to some extent, dihedral groups). But if I had known about it at the time, I could have used Hashing in Unordered Multisets as a touchstone example to build up finite abelian group theory, as it covers all the main components of the theory, such as group actions and the classification of finite abelian groups.
Learning as you go
Here you document the learning process over a series of smaller articles as you learn it yourself. It's good fodder if you can't think of anything to write, because it forces you to learn the material better by reorganizing it in your own words.
The trap here is falling into a pattern of repeating the order or structure of an existing book. It makes the writing process much more boring. It's better to revolve this around your own examples and personal thoughts and confusions. E.g., you might have misread a definition, and then overcome it by finding an example that needs the missing part of the definition.
Finally, this mode of writing makes the "what if I try a naive idea" feel more genuine, because it is you actually trying out naive ideas, and recording the ones that aren't too silly.
Some examples include a series of 4 articles on Silent Duels and handful of articles like this one on the math behind fully homomorphic encryption, which I'm learning as I officially joined the field six months ago.
Commit by commit
In this style you are showing the evolution of a software project over time. You write explaining how a project is built up, and then you link to specific commits and pull requests as demonstration.
It helps particularly in showing how some ideas navigate into a proper codebase in situ. And if you organize the commits well, you can isolate the changes that are really useful to expose in the writing, while boilerplate and formatting and all that other stuff is skipped. This also gives the reader a means to check out the codebase at a given commit to experiment.
The hard part here is ensuring the commits are clean enough, and that the project is functional at the intermediate commits, so that a reader who engages with it won't be too lost or stuck. Small commits are your friend here.
I did this technique only once, with a series of 9 articles on searching for Riemann Hypothesis counterexamples. The main goal there was to teach some software engineering ideas, not so much the math, but I think it could work well for math as well. Say, to demonstrate the nuances of math when it gets into an actual program (e.g. how it can help or hurt in integration, testing, or maintenance).
The "what if" trickle
Perhaps the most popular form of math writing out there: the style that is popular among internet math superstars like Grant Sanderson, Vi Hart, and the Numberphile crew. It usually has the structure of "trickling" the reader along with a series of "but what if..." questions. "But what if we tried multiplying these two things that have no business being multiplied? Is it even possible to make sense of that?" It often requires some suspension of disbelief on the reader's part, especially when treating a topic like complex numbers where you really are starting with "illegal" operations but perform them anyway to see what falls out.
These work, and are great for the kind of content where the reader is swept away on a mathematical joy ride, passively watching as the expert reveals the magic trick. This format doesn't always land well, particularly when the thing you're talking about isn't as smoothly ironed out as, say, Fourier analysis or a classical math puzzle. If you can't rest on decades of prior insights and explanations, or if your topic is esoteric, or if you feel like you're the first one to widely communicate a particular insight, you have to be deliberate about why the reader should care about what you have to say. My focused insights about error growth in homomorphic encryption key switching is never going to be on Numberphile, but it's extremely hard to find proper documentation about it, and what you can find universally describes it as "well known" and omits the details. I provide the details. That sort of content will never fit well in the "what if" trickle.
What about you?
What sorts of formulas have you developed for writing technical content? What works and what doesn't? Reply to the email and let me know your thoughts. It's way friendlier than internet comment threads.