Writing can be difficult. Writing about technical topics and code presents unique challenges. For instance, while code may be engaging to write, it isn't naturally engaging to read. Trying to write solid technical blog posts and make them interesting is not an easy skill.
In this article, I want to go over a few things that I have learned that may be helpful to you when writing a technical blog post or article. Just to give you a quick background, I wrote my first published article in 2004 (for the ColdFusion Developers Journal, which, at the time, was a print journal). I started blogging at the start of 2005, and since then I've written a lot of articles, but also managed developer content at Adobe, Telerik and now Progress. In the process, I've written, edited and read a ton of technical posts, and these tips are some of what I've found to be most effective based on those experiences.
I first wrote about this topic 4 years ago but thought it worth revisiting.
NOTE: As I was preparing to post this, I found that Wade Christensen posted on the same topic but with slightly different angles. I think he offers some excellent advice and that our advice doesn't really overlap to any great degree. So read his post as well!
Make Your Intentions Clear
As a reader, there are multiple decision points for choosing to read or comlete a post. The intial one is typically, "Does the title make the article sound interesting?" If the title interests a reader, they'll typically read the intro and decide, "Is it worth my time reading the whole thing?" A common mistake I see in a lot of technical posts is either too much introduction or, alternatively, far too little. In both cases, the problem is that the intention of the article can be unclear for the reader, who may abandon the post early.
The case of too little introduction is usually one where the writer jumps too quickly into the code without much in the way of setting the stage. Unless the title and the content are inherently self-explanatory, a little bit of intro is necessary to not leave the reader disoriented.
In other cases, there are numerous long paragraphs of introduction, often before the author states the actual intention of the post - if they state it at all. In these cases, the reader often is looking ot understand the scope of the post and make their decision about whether it is worth reading, but the author is making them work too hard for it.
Here are my tips to make your intentions clear:
- Keep your title crisp and descriptive. In my opinion, catchy titles aren't "click-bait" as long as they are accurate - so you can still feel free to be creative.
- Keep your introduction to no more than a couple paragraphs if possible. If a lot of background information is necessary, often what works is to have a quick paragraph intro laying just the goals of the post and then put the remaining background information into a seperate section immediately following the brief intro.
- Have a sentence in your intro that clearly states what the goals of the post are. Something along the lines of "In this article, I plan to..." or "In this post, we'll discuss..." This can both help to clarify your intent to the reader and refine your writing to not stray from your intended goals.
Break the Wall of Text (or Code)
A wall of text can be visually intimidating to a reader. I know, I am a master at the wall of text - if it can be said in 3 words, I can easily manage to turn it into 3 paragraphs. So this is advice that I admittedly fail on from time to time.
However, the wall of text can be easily be made less intimidating and appear much more visually appealing through the use of visual elements that break it up. The easiest is to simply place section subheadings throughout your post. This not only breaks up the wall of text visually, but it also helps the reader scan the content in order to find the information they are looking for or even when deciding if it is worth reading in its entirety. In a similar fashion, lists can also break up the visual monotony and improve scannability.
Wherever relevant, use images and/or video liberally. This makes posts seem much more visually appealing and engaging, while also reinforcing or enhancing concepts. If you are able, including live code demos using tools like CodePen or jsFiddle are also excellent.
Here are tips for breaking up the wall of text/code:
- Use subheadings to break the article into multiple sections. If a section gets too long, feel free to break that into further subsections.
- Use images, video, memes, gifs wherever relevant to make your content more visually interesting.
- Wherever possible, use tools to embed runnable code into your post. This not only makes it more interactive, but also can break up huge blocks of code into a more compact embed.
Be Yourself, But Know Your Audience
Depending on where you are publishing, there are varying levels of formality. If you are publishing to dev.to or your own blog (or both 👍), the formality around language, grammar and punctuation is especially casual. However, if you are writing for a technical journal or magazine, you may need to adopt a more formal voice. This doesn't mean you can't have your own voice and style (in fact, you should!), but it does mean you may need to adopt a less casual voice and tone down on the emoji or memes, for instance.
The other important thing to note is the audience that you are writing for. If you are writing for a technical beginner, you should either avoid jargon (which is generally a good idea anyway) or be sure to clearly define it. However, if you are writing for a tech journal that serves a more business audience, you may need to ensure you clearly explain some technical assumptions you may typically make about a developer audience (not saying anyone is dumb here, just that they may not be as familiar with some of the tools and jargon that developers take for granted).
That being said, not every post needs to get bogged down in explanation. It is fine to refer to other external resources for additional information should your article require some degree of prerequisite knowledge.
Here are some tips for being yourself and knowing your audience:
- Feel free to have a writing style and voice that is unique and represents you - this is what can make an article interesting. Some editors can inadvertently wash away that voice, but you should defend it whenever possible.
- Adapt for the audience you are targeting. That means you may need to adopt a more formal voice (without burying your style) in some cases, but it also means you may need to understand the technical skill level of the audience you are trying to reach. Try to avoid jargon or, when jargon is necessary, ensure that you define it or include a link to a definition.
- Don't let concern for your audience push you to over-explain. It is fine to rely on external resources for prerequisite knowledge or tangential information that may distract from the goal of your post.
What are your suggestions?
As I noted in the intro, Wade Christensen has an outstanding post on this topic as well that has some really good suggestions that delves deeper into topics around grammar and language. How about you? Do you have any suggestions based on your experiences about how to write better technical content?
Top comments (5)
Hi Brian! This article is great and I absolutely needed it seeing as I just completed editing a technical article I wrote. I was really conscious of a few things.
I had a few concerns and I'll like to know what you think.
When writing a post that has heavy technical content i.e code blocks. What do you recommend?
Thanks Egwuenu! For the code blocks, if the entire block isn't relevant to the discussion, I'd include only the relevant portion and a link to GitHub for the full source. Sometimes I even replace irrelevant portions, like inner code on functions or elements, with a
..., though this should be used carefully as some may find it confusing if it hides a portion of code that would improve their understanding.Alright Thank you.
I think we should always strive to make it easy to understand besides avoiding technical jargon.
Indeed, if it can be said simply then it should be said simply.