5 easy features to make Substack shine for Technical Writing

A few ideas on how Substack could improve our experience.

Substack is already one of the best places to write online, mostly because the community of writers is so incredibly kind, and the networking effects are real. However, Substack lacks tool support for technical writing in several ways.

In this short post, I will highlight five hugely useful and reasonably easy-to-implement features for technical writers that would elevate Substack to the best online tool for our breed.

I will cover editing, organization, and monetization. Feel free to comment and add any suggestions you think would also be helpful for your writing workflows.

While I have zero leverage with Substack developers, I do hope this post gets in the eye of someone with the power to push for some of these changes. I think it would be a win-win.

---

#1 - Support for code syntax

This is a must for technical writers in the computer science and software engineering area. It is simply too cumbersome to share code today in Substack. Our best options are either the severely lacking native code block (which is just a monospace font) or embedding a GitHub Gist —or worse, an image.

On the other hand, this is so easy to implement that it is inconceivable that Substack still hasn’t solved it. There are dozens of fancy text editors with support for syntax highlight that could be included in Substack.

One argument I hear a lot is that Substack prioritizes the email experience, and email is very limited in what you can do with CSS. However, possible solutions involve either rendering an image version of the code, or falling back to a less fancy rendering on email with a generated link to the web version for those who want to see the code block in its full splendor.

#2 - Series with custom navigation

Many of us write a series of posts on a given topic. The usual way to organize them is to put something in the title (e.g., “Foundations of CS #1 - The actual title”) and/or to use a custom tag.

However, since there is no notion of an actual series, there is no built-in navigation. So, we have to manually add navigation links, which means we have to edit past posts to add forward navigation. The native navigation links work across your entire publication, so if you’re writing two series simultaneously, the links will get mangled.

An easy solution is for Substack to allow defining an arbitrary tag as a series, which would potentially add native back/forward navigation links among the series' articles. Also, one could optionally define that a given tag lists posts in increasing order (older to newer) instead of the default (newer first) when reading articles in chronological order makes sense.

#3 - Conditional sections

As a software engineer, one of the mantras I live for is DRY — Don’t Repeat Yourself. When writing a piece for non-, free, and paid subscribers, I have to consider how different readers will see my article and add pieces here and there that only make sense for some of them.

Conditional sections would allow us to mark some sections as free-only, paid-only, non-subscribed-only, etc. Right now, the only feature reasonable close is the paywall which basically divides the article into an intro that everyone sees and a full content that only paid subscribers see. However, there is no way to put something only for free subscribers, for example.

Ideally, I would want to make a section conditional on any of the filters they allow on the subscribers page. For example, I could make a section that only appears for first-time readers, or, on the contrary, for my 5-star readers.

#4 - Pay for single posts

This one is a bit harder because it probably messes with the business model that Substack consider optimal —the long term subscriber. While I do live my yearly subscribers, I also recognize that some readers won’t get a full subscription just to read one paywalled article that interests them.

The solution is, of course, to extend the payment mechanisms to allow us to charge for individual posts. Even better, give us a fully customizable tiered system where I can offer different things to different categories of subscribers, as complex as I want.

Right now, we only have three fixed tiers: free, paid, and founders. If I now want to offer, for example, a paid course, I have to either make it accessible to all paid subscribers or manage payment outside Substack. They are leaving a lot of money on the table for the lack of a more full-featured payment system.

5 - Global or category-based tags with search

I love tags, as they allow me to organize my articles in non-disjoint categories (as opposed to sections) and then link to the list of all relevant articles on a given topic by using a /t/ URL. However, unless you decide to put links to your tags, they are invisible to me as a reader. Furthermore, I’m sure several publications use similar tags (e.g., many of us have a programming tag or something similar).

What if, when adding a tag, Substack would suggest similar tags used around the community (category) I’m in so that later readers could find individual articles by tag on the Discover page?

Right now, for the most part, different substacks are different silos. Unless explicitly linked to them, navigating among similar publications or finding relevant articles related to what you just read is almost impossible. While going full automatic recommendation is something I understand they are cautious of —we’re all sick of the algorithms dictating what we consume— searchable tags can give writers and readers the power to find what they want transparently.

---

That’s it for today. These are just five relatively easy-to-implement features that I believe would elevate Substack to a different level altogether. As a software engineer, I understand that all features need to be balanced in terms of complexity versus the value they provide, but I truly believe these are absolutely worth it.

What do you think? Is there something obvious that Substack doesn’t provide and would make your writing so much easier?