What every good blogging tool must have

2024-12-09. Updated 2024-12-13

There is a single requirement that a software developer needs from any good blogging software. Every software developer needs this, and no blogging software out there does it.

As a software developer, I must be able to pick up and use your tool in less than 10 minutes to generate a lovely, generic, static blog from my pre-existing Markdown source under source control with no modifications and no learning required.

This is the MVP requirement. Nothing short of this will do. And yet, every blogging software I’ve ever tried falls short of that in some way.

Why?

Before I break down this dense statement into particulars, I’ll motivate it. Whenever you start a blog — especially your first blog — you have a number of impediments that must be resolved before you can publish even one post.

This is what keeps 99% of software developers from blogging; and it’s exactly what keeps potential bloggers from using your tool. Or, switching to your tool.

Your goal, as the author of a hopefully-popular blogging tool, is to remove as many of those impediments as possible, while absolutely never — under no circumstances — adding new ones!

This allows your users to download your tool, try it once and say, “Good enough,” then go back to solving their core problem: being consistent with writing output.

What?

Let’s break it down, bit by bit.

The user

As a software developer,

Limiting your audience to software developers is cheating, and you know it. To say it another way, if you assume all your users have a decade of software development experience and you can’t get the initial setup process under 10 minutes, it’s not them: it’s you.

By assuming your users are all software developers, then you can can make tons of UI or technical mistakes as long as you don’t make a single UX mistake. The user experience has to be on point.

A developer of what skill level? Let’s keep it simple. Someone you would consider a peer; but who has no previous experience with your product, or with creating one’s own blog.

You’re smart enough to create a blogging tool, so someone like you should be able to use a good blogging tool within a few seconds, right?

As a software developer, I don’t even mind a short debugging session after downloading a new tool, as long as I happen to have the knowledge to get past it already and as long as I’m not already frustrated from debugging another crappy blogging tool.

Obviously, this debugging session will unnecessarily filter out potential users, and it shouldn’t exist. The point is, developers can tolerate a lot more than your average user, and by targeting them, you’re already cheating by a wide margin.

There’s zero excuse for not meeting the rest of the MVP requirement. If you can’t, you should feel a little bad about it.

pick up and use your tool in less than 10 minutes… with no learning required

This is a big one. I’m your potential new user, and I have just downloaded and attempted to use between 10 and 30 other blogging tools. All of them were cumbersome, some of them looked like crap. None of them met the MVP requirement. Now, I’m in a bad mood, and my patience is thin.

Finally, I’ve discovered your tool, on the second page of search results. Here’s your task.

You need to win me over within 10 seconds on your website; then you need to engage me within 30 seconds (to try and use your tool); After a minute, you’re wed (user understands how to generate a blog); within 5 minutes, you’re renewing your vows (first output generated, looks okay…); after 10 minutes, you’ve lived happily ever after, and have had a fulfilled first install together (site is “good enough” for the user to start writing and stop learning).

A great way to do that is with a Github README that includes a Getting Started section. (Remember how I said that choosing software developers as an audience was cheating?)

That Getting Started section should be short, self-contained, and enough to get the user to the point of generating an output within 5 minutes of noticing that your tool exists.

It should be immediately followed by documentation of common use cases, in a format that is succinct enough to get me to accept your blog product as “good enough for now” within 5 minutes of additional effort.

Again, because you’re targeting software developers, you can cheat here. Your product can take 5 minutes just to produce an output as long as there’s a clear indication of progress and that 5 minutes doesn’t require any additional user interaction or effort.

Just know that while I wait, I’m dating another blogging tool and making unsavory comparisons.

The product

a lovely, generic static site

The default output of the site must be attractive, both in code and prose. It must not be offensive in the context of the modern web:

1. It must work on all devices (including RSS feed readers).
2. It should be accessible (color contrast; semantic markup, etc).
3. It should be well-behaved — responsive, progressively enhanced, etc.

It does not have to match your user’s taste. If you can give the user 3-5 suitably bland default presets for appearance and/or site layout without requiring additional work, that’s above and beyond!

It must support all the features that every single blog has. It does not need to support all the features that every blog should have: just the ones that make it a blog.

For example, a blog without a tag index is still a blog. A blog without a dark mode cookie is still a blog. (<article> plus Firefox gives you dark mode for free, anyway.) It doesn’t have to be a good blog, yet; because after all, there’s only one post so far: this is a new user.

It does not have to support a general website. It doesn’t need an about me page. It doesn’t need any pages except a paginated blog index and the blog posts themselves. It does need to be self-contained.

Supporting additional pages is nice to have; but if the user can shove your blog output into a subfolder of an existing web site, that’s good enough.

The source

from my pre-existing Markdown source … with no modifications

I should be able to write a first blog post in any Markdown format of my choosing before I discover your tool; and your tool should produce a reasonable output from whatever I did.

If I look at the post output, I should not see any missing text or formatting errors. Code, blockquotes and tables should be properly formatted.

With no modifications. No preamble. No additional metadata. No

status=published
date=2024-12-09
======

garbage. You can assume everything is published and order the posts alphabetically by filename for all I care. Just give me the output!

Why Markdown? Because your user has heard of it before. It’s good to support ReStructured Text; or docwiki; or Confluence; or ePUB; or whatever. But you must support Markdown!

It’s not even hard anymore. Just bundle and wrap pandoc and call it a day!

under source control

Your product should be targeting a responsible, mature adult. It shouldn’t merely be for teenagers or young adults who haven’t learned to appreciate their family history, yet.

Target a legacy of integrity and prestige; not whims of burning passion.

Actually, you should support your users’ burning passions, too. But you shouldn’t lock them into a workflow that prevents meaningful change and history management.

I should be able to delete all of my blog, then clone it back down and regenerate it without ever committing a single file that was output by your tool.

This doesn’t mean that everything has to follow that rule. Not all of my customizations have to be source-only. It doesn’t mean you can’t output a skeleton site template and encourage me to customize it by hand, for instance; but it means that an MVP blog can be regenerated without any of that.

I’ve recently tried a blogging tool that allows you to type Markdown into an editor window, but then uses the HTML output as its actual source. It won’t even notice if you add a new Markdown file. Instead, you have to paste your Markdown into its workflow at the right moment, and then version control the stupid HTML file it outputs.

If I were willing to read and write bare HTML on a regular basis, why would I even need a blogging tool? That’s not a niche! There are no users!

Why is this so uncommon?

By the time your user has gotten a static output that he is generally pleased with — and is willing to share with a stranger — he is already deeply invested in your product. He is no longer a new user.

Accordingly, behind any blog you see (which could possibly have been recommended to you by someone you haven’t met in person) is a blog owner who is already deeply invested in some blogging tool or other.

Established users have completely different requirements from new users. Established users need customization and control in order to stay with your product.

New users need output — any output. And they need to get busy writing, right away. Don’t make your MVP support every every customization and feature they’re all craving.

Get each of them to say, “Good enough for now” within 10 minutes of downloading it, and to have a sigh of relief because all the impediments to publishing a first post have been removed.