How to write a technical article?
Developer’s secret guide for an awesome article
We know you can code, but can you can a decent technical article?
That was the question that I asked myself three years ago.
There’s no secret that when developers are stuck we turn to the internet for the answer.
I reason why I started writing was that I wanted to contribute my share of knowledge.
But have you ever looked up some technical article that just frustrates you rather than giving you the relief?
Whatever your motive is for writing a technical article(I’m sure it’s a good intention), the little guideline wouldn’t hurt.
Start with the Purpose
What kind of article is it?
- Tutorial
- New Tech Introduction
- Deep Technical Dive in topic X
- Bug Solution
- Resource List
This is not an exhaustive list. A technical article can come in different shapes and sizes.
The important thing is that your article serves this ONE purpose.
A tutorial should be more detailed and step by step.
As opposed to a new tech introduction, the reader just wants to know what news about ____, and share it on his or her social media.
Spend more time with your Headline
Most people only judge an article by the headline.
Your headline should:
- Convey the purpose
- Stir up readers’ interest
Also, add a relevant image to the top, because when people share your article that’s the image thumbnail.
We will talk more about images later.
Here’s also a tool for analyzing your headline. Keep in mind that this kind of tool changes all the time. If this service becomes unavailable, you can always google “Headline Analyzer”
If you know other awesome software that can help writers, please let me know in the comment.👀
Ways to Include your Code
- Code for copy and paste
- Pretty Code
- Interactive Code
Copyable Code
If the article is a solution to a bug, 99% of the time people just want to copy and paste.
The easiest way on Medium will be adding ``` on the new line. Like below
// Hi this is a comment
var greeting = "hi";Or if you want to talk about a variable in the middle of the sentence, you can add ` before the code.
Like this, this
Or if you would like more formatting and syntax highlighting, you can use Github Gist and embed it in the article.
Pretty Code
If your code is more of information to illustrate a point, you can present your code in a pretty way.
Online tools like Carbon. Create a beautiful image of the code.
There is also a Visual Studio Code extension that lets you create an image like this.
Interactive Code
Sometimes the best way for your readers to learn is to let them tinker with the code. Change some things around and see the changes for themselves.
There are many platforms for you to demo interactive code, but I found Replit.com offers the most comprehensive functionality.
In the good old days, you could just create a Replit account then copy-paste the link in Medium.
However, since Replit changed its domain from repl.it to replit.com you will need to change the URL a bit for it to work.
The reason being the embed provider that Medium uses: Embedly still uses the old URL scheme of repl.it
This is what it will look like:
For frontend showcase, Codepen is also a good option.
Explain your Code
Just like how you write comments for your code. Some code by itself will be hard to understand.
Imagine you’re writing for yourself one year ago. Or whenever you started learning how to code.
This is how you can help junior developers become senior developers. They will move from copy and paste to understanding why and how it works.
Image, Screenshot, and Emoji are 🔥
Stock Photo
On Medium, it’s very simple to include a stock photo for an article.
Press the Plus button on the left side of a new line
And then select the Search button
Then you can search for a stock photo on Unsplash by keyword.
It only takes a few seconds, but it makes your article looks more visually appealing.
Screenshot
The way I wrote about how to include a stock photo on Medium also demonstrates how you do a screenshot.
After taking a screenshot, you can always include a red arrow or boxes to guide the reader to the exact spot.
This is very useful when you’re teaching someone how to use some graphical interface.
For example,
Useful shortcut for Visual Studio Code
How to enable ___ setting for your IDE
GIFs
GIF is a wonderful way to demonstrate a user interface or demo your app.
Because when people are reading, they don’t want to start watching a video.
A GIF offers more motion to illustrate a point.
For example, in my last article, I did a breakdown of IKEA’s WeChat mini-program. It will be hard to demonstrate the animation of the search bar without some motion.
Emoji
Lastly, to add some personality, you can always add some emoji
Emojipedia is the best source for you to find all kinds of emojis.
Spelling and Grammar still Matters
Incorrect spelling and grammar will create confusion, and it drives OCD people nuts.
If your first language is not English, it can be hard to tell if you’re writing correct grammar.
That’s why I use Grammarly Chrome Extension
And it’s always good to proofread it once or twice.
If you have someone else who can help you quickly skim through, even better.
Conclusion
I hope this article can inspire you to help more people with your writing.
