Sign in Subscribe
Tutorial

How I, someone who writes about obscure technical things, will improve my writing for you, a beginner

Michael Marner

• 2 min read
How I, someone who writes about obscure technical things, will improve my writing for you, a beginner
It's a sulfur crested cockatoo on a tree branch!

There's a post that's been doing the rounds that's worth a read:

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie’s blog
“Hello! I am a developer. Here is my relevant experience: I code in Hoobijag and sometimes jabbernocks and of course ABCDE++++ (but never ABCDE+/^+ are you kidding? ha!)  and I like working with Shoobababoo and occasionally kleptomitrons. I’ve gotten to work for Company1 doing Shoobaboo-ing code things and that’s what led me to the Snarfus. So, let’s dive in! 
annie's blog

It's tongue-in-cheek, but I think the issues are real. People writing tech tutorials, or even about technical topics in general have no idea about who their audience really is. They tend to assume way too much prior knowledge, which makes the writing way too difficult to understand.

In the past I have ignored this issue because I figured, well, if someone is going to the effort to type "ory kratos haveibeenpwned" into Google then they already know what they are getting themselves into. The assumed knowledge is implied by how obscure the topic is.

But that's not fair to people who stumble upon writing by accident, or read some of what I write for different reasons. And so, my pledge to you, dear reader:

  1. Going forward, technical articles will include a callout explaining who it is for, and what you need to know going in
  2. I'll do my best to include more links throughout. If you don't know what Hoobijag is, then there should be a link.
  3. I will never provide code samples or console commands without explaining what they do
  4. I will never try and be funny or chummy in a technical article, AMIRIGHT!?
  5. I will never, ever, use the term "basically"
  6. I'll try and backfill this on my old writing too

It could look something like this:

💡
This is a tutorial using Snarfus, a programming framework for APIs. In it we look at getting fisterfunk, a messague queue to talk to the Shamrock Portal, a way of sending emails using an API. This is important because it allows you to efficiently send lots of emails to your app's users.

At some point, blogs about obscure technical issues need to assume some knowlege, or each post will be a self-contained thesis. Maybe we need more explainers to beginners before diving in?

To be honest, I'm not entirely sure what this website is for exactly. I want to write more, both because it's good for me, but also because I think we need to de-evolve the web from the Big Platforms back to blogs and forums, and so I can be a small part of that. I'm doing less obscure stuff than when I was a PhD student and so I don't know exactly where I fit.

But all of us who do any kind of technical writing owe it to our audience to be understandable. Annie's post may have been in jest, but there's a real truth in there.

We can and should do better.