8 Steps Towards A More Publishable Technical Blogpost
A Protocol To Ensure Your Blog’s Excellence
A hiring manager finds your blog post about a certain SQL aggregate function and its use-cases specifically within financial records and sends you a message over Medium to check out the new SQL-heavy position at their workplace. They think you’d be a great fit. A recruiter reads your blog post about why scikit-learn has the best-written documentation compared to other python machine learning packages, and wants to talk with you about a new ML engineer position that their boss is hiring for. An amazing technical publication wants to pick up your most recent blog post on your experiences at the latest hackathon, and in doing so your name gets mentioned in a digital room full of opportunities. That’s the dream, right?
Blogging is showcasing our skill sets as technologists, (in my case, as a data scientist.) While blogging improves your written communication skills, and how you explain your ideas to others, blogging can also have the very real consequence of getting you hired for your next job. Publishing your blog will only increase the scope of who discovers your skills.
But how to write a blog that showcases those written communication skills? With APIs, we can look up the documentation to make sure we are using the correct parameters to return the information we need. But where is the documentation for making a good technical blog?
This blog post attempts to provide some of that structure. It can be thought of as a protocol, a set of guidelines or a checklist, whatever framework you like. These steps were born out of the workshop Blogs That Will Get You Noticed that I developed and presented to Flatiron School twice now, while being a student there, as a supplement to their curriculum. I developed that workshop after my first blog post was published by CodeX. After my last blog post was accepted as an Editor’s Pick in Towards Data Science, I knew I had something to offer the greater technical blogging community here on Medium.
Without further posturing, here is that protocol, Eight Steps Towards A More Publishable Technical Blogpost.
1) The HOOK: how do you capture your audience’s attention?
Let me bring your attention to Medium and how previewing articles works on this site specifically. I searched Medium for “how to blog” and here are the first two results that popped: How to Blog the Post-Pandemic Way by Jason Weiland and How to Blog: A guide for non-bloggers by Haje Jan Kamps.
Both look interesting! If you only had time to read one how would you choose? The title, the accompanying picture, the publication, or maybe the tags, but probably you read those three lines of prose that Medium.com previewed for you, right?
A hook is something that grabs the reader's attention right away and sparks their interest so they want to keep reading. On Medium we have something equivalent to the length of a Twitter post to inspire our readers to click on our blog article. And the hook to our article is competing with the hooks of other articles for that singular click.
This idea comes from creative writing conventions but is essential to technical blogging. After all, if you were looking for a blog article about using Seaborn for example, which article would you click on first based on just the first line:
A: “MatPlotLib is a python library for data visualization, a beautiful but complex monster of different syntaxes which Seaborn was built on top of, as a way to regain some sanity.”
B: “MatPlotLib is a python library for data visualization. Seaborn was built on top of MatPlotLib as its own library with much more consistent syntax.”
They’re very similar and are about to discuss the very same information. So why does A sound so much more fun to read? What does B lack? When writing A, I used evocative language ie “regain some sanity.” I let more of my personality and opinions show in my writing. B, by contrast, is very dry and feels, for lack of a better word, kind of blah to read. A also used language that put a picture in my reader’s head, using “a beautiful but complex monster.” B by contrast is less engaging of the readers' visual imagination.
Here’s an example of a great hook from popular media:
“I was 12 going on 13 the first time I saw a dead human being.” — first line of the film Stand By Me, written by Richard Dreyfuss based on the novella by Stephen King
This hook uses the unexpected to get the viewer’s attention. It immediately fills the viewer's head with further questions about said dead body, and why the narrator had access to one at the age of 12. Curiosity is a powerful kind of attention to capture your readers.
Another strategy for building a good hook is to start by thinking of what your reader would be most interested in, and giving it to them in the first line. I used that strategy to get you (hopefully) reading this blog post, by saying a hiring manager finds your blog post… In those seven words, I am already talking directly to the reader, (you,) and potentially finding a job, something I am guessing you are very interested in.
But what do we do with that attention once we’ve earned it?
2) The MESSAGE: what do you want your reader to know by the end of reading your blog post?
You are going to say very many amazing and intelligent things in your blog posts. You probably want your reader to leave your blog post with more than one thought on their mind. So what constitutes a message and why is it important to have one?
A message here is defined as one overarching thesis, an umbrella statement that every line of your post will point to or prove true. The message could also be framed as the thing your audience is looking for.
The message of this particular blog post could be stated as “if you do these eight steps when writing, your blog post will be more publishable.”
Having a clear message before you start writing is similar to pseudo coding a function. Here, I’ll use a simple function as an example:
f(x) = x + m
You are inputting x and the function will result in an output of x + whatever m contains.
If the reader is x, and the act of reading your writing is the function, then the input is your reader before reading your writing, and the output is your reader + m where m represents the message of your writing.
This might sound simplistic but thinking of your writing as a definitive value that your reader will leave with at the end of your article, will help your clarity, your focus, and your reader’s understanding.
3) The TECHNICAL CLARITY: how well can someone understand the concepts you are explaining?
Technical clarity is essential, especially with the rigorous amount of technical knowledge some of your blog posts attempt to summarize and illustrate. So often I find myself going to technical blogs, specifically when there is something technical that I’m struggling to understand. There are many ways to go about making your technical writing clear, and here are a few:
- get feedback on your writing from someone who thinks very differently than you, they may be able to point out your blind spots (where your own expertise on a subject prevents you from understanding how a novice might misunderstand that subject)
- try and anticipate where something may be ambiguous and spend extra time explaining where folks may get lost
- explain the same idea in a few different ways to cater to different kinds of intelligence (ie linguistically or by using analogies, visually, mathwize, etc)
- try and break down complex procedures by going in a detailed linear order, as if you were explaining how a recipe worked
- showcase examples of what you are trying to explain
- explain jargon, acronyms, and vocabulary in plain language
My biggest tip for technical clarity is to put yourself in the mind of two very specific people: an expert in your field but who is, perhaps, very drunk, very tired, or very distracted, and a very intelligent space alien who knows absolutely nothing about your field.
If you can lead this party of two through the technical aspects of your writing, you have done an amazing job!
3) The AUDIENCE: who was your blog article designed to be read by?
This blog article is designed to be read by technical writers who are looking to publish their blogs, and potentially get hired. I know this because that audience, (you,) is who I keep addressing.
Now, it’s a good attitude to have, thinking that all blog articles you are writing are for a hiring manager, a recruiter, or your next boss to read. This attitude will help you not only stay motivated when writing but keep you on your best game.
However, most of the time, you’ll not be writing to them directly as the primary audience for your technical blog. That’s what cover letters are for!
Whether your blog article is for code newbies looking to execute their first line of code with a print(“hello world”), or you are looking to discuss the intricacies of pre-processing data, you can signal to your audience “hey, I see you. I’m here to talk to you specifically.”
A very simple and direct example of choosing your audience that you might be familiar with in advertising is a list of questions about the audience where the audience can answer “yes” to each question.
For a non-technical example, if I was writing a post about how to pick out a new washer/dryer, I could use this as both my hook, and to define my audience: Are you tired of going to the laundromat? Sick of the fluorescent lights, and the quarter machine rejecting your dollar bills? Are you considering buying a new Washer/Dryer? If so, this post is for you!
There are a lot of less direct ways to go about defining your audience in your writing, but I find that if I chose my audience before I start writing, then I will unconsciously fit my article to that audience. But, when in doubt, the sales pitch approach described above is a functional framework. The goal here is to make the reader feel seen and welcomed.
5) The IMAGES: what will your reader see in your blog?
(*Please note, this section is written under the assumption that you, my reader, are a primarily visual reader.)
This blog, no matter how interesting the words may be, will have a much more impactful and fascinating effect on my readers if I include relevant images. The human eye can respond to color, to composition and will often try to make a story out of the pictures in an article.
So far in this blog, I’ve used a screenshot of the return from a search on Medium, and a series of images from Upslash. I’ve introduced each image with either a phrase or an idea, so the reader can connect that image to my overall message.
There’s a reason why The New York Times tends to put a large image with their headlines. Let’s explore the picture below for a non-technical example. The image below gives us a single word: cliffhanger, and a picture of Donald Trump. What meaning does the word “cliffhanger” mean when paired with this image and how does that meaning change if the image isn’t provided?
A good image (or video) will break up the monotony of the text in your blog post, but a great image will reinforce a concept or prove what your writing is trying to say.
To prove my point, let’s do an experiment with something technical. I made this video for my post Using Folium on Police Data last month, using data from NYC OpenData about Stop and Frisks from 2020. Hit play and close your eyes.
Pretty boring right? And it may not lend itself much to your understanding of what this data set looked like.
Now try rewatching it with your eyes open. Now you can see as I narrate, just how unwieldy that data set was to work with. Your visual understanding of the video adds meaning to my narration.
Don’t be afraid to make your own videos of your technical processes!
6) The CODE: what does your code do or prove?
Your code is evidence of your intelligence, your process, and your technical prowess. Adding snippets of code, by using GitHub’s Gists for example, is a surefire way to increase the tactical wow factor in whatever your blog is about. What could be more straightforward than having enough code in your blog about your code?
(Documentation of GitHub’s Gists here.)
But what makes a good gist? Let’s use that recipe metaphor again. All gists and images for that matter can follow this order of operations:
- introduce what the gist will show like I just did above
- include the gist
- state in plain language what the above gist just displayed
If I was writing a technical blog about how to print three strings in python. I could just put all my code in one block, like so:
The above code defines three strings. I create the object “all_strings” where the three strings are concatenated. Then I use a print statement which will then show me the output as
Hello World! Thanks for reading my blog, I hope you learned something useful.This wouldn’t be the worst thing in the world for this tiny bit of code. It’s pretty simplistic for who this blog article was designed for. But what if the audience was folks who’d never coded (in python) before?
Then I’d probably want to unpack this code by breaking it down into three gists, and comment on each step.
The code above shows how I was able to create my three strings. Note how in string1 and string2, the last character is an empty space, since python will not automatically add empty space to the end of each string. Strings are made up of characters and are wrapped in either single-parenthesis ‘’ or double parenthesis “” syntactically.
Next, I’m going to concatenate these three strings which means sticking them together. Concatenation keeps the original order of each object concatenated. You can think of strings here as letters in a word. Each letter starts at the end of the last letter and the order of A + P + P + L + E turns into APPLE using this method, keeping the order intact.
The code above shows how to do that concatenation. Finally, I’m going to print all_strings, so we can see the output.
The above code will return:
Hello World! Thanks for reading my blog, I hope you learned something useful.Keep your audience in mind when you display your code, and let your audience guide you when you are asking yourself “how much should I break down and explain my code during my blog post.”
7) The AUTHOR: who are you and what do you bring to the article you are writing?
How much detail you include in your technical blog about who you are is a choice you are going to have to make for yourself. It’s a personal question of boundaries.
You have an opportunity to choose how you’d like to present yourself. You can do this directly, as I did in the introduction to this article, by telling you how I developed this blog article and my publication history. You can and will do this undirectly, in every choice you make while blogging. Your cadence, your vocabulary, your message, how you chose your images and how you wrote your code, etc, are all going to paint a picture of you in the mind of your audience.
This is something to lean into, in my opinion. I read a lot of blogs where the author’s voice will sound either like a college essay or even more impersonally, like documentation. I would encourage you to use your own voice when writing as if you were speaking to a friend, family member, or a mentor/boss with whom you have a good rapport. There are a million college-style essays to read, and documentation to go through, but there is only one you in the world, and that’s already more interesting to read.
8) The CONCLUSION: how do you want to end your article?
You’ve probably heard the phrase “start strong, end strong.” Your conclusion can be thought of as your reader reaching the final destination on a journey. It’s when your reader steps off the plane at the airport and thinks to themselves “I was there, and now, I’m here.”
Your conclusion is an opportunity to make sure your message hits home, to recall the journey that your reader has gone on with you, and perhaps ask new questions of your reader, so they can see this blog in a new light.
For example:
In this blog article, we read about how to capture your audience's attention, how to choose images to include in your article, and how to unpack your code for readers. We also discussed why having a clear idea about the message you want to get across, as well as a specific intended audience can help your audience find that message. Additionally, we went over strategies for providing technical clarity, and I encouraged you to speak in your own voice when writing. To conclude, I’m going to show you an example of a conclusion, and emphasize that by following these eight steps showcased, your writing will be clearer, more interesting to read, publishable, and potentially get you your next job interview. After all, you never know who will be reading your blog in the future!
Taking this a step further, if you were to write an article about how to write articles, as I have attempted, what would you do differently? Are there any tips or tricks you’d share with your readers about getting published? What are your secret methods for writing technical blogs?
Conclusions are your opportunity to leave a lasting impression and reward your reader for reading the entire article. My hope is that you leave this blog article feeling empowered to write and explain your ideas. After all, there is no shortage of genius in the Data Science community on Medium, and my personal investment is that I want to be able to understand your ideas when I read your technical blogs.
