loading...
Cover image for 5 Tips for Writing Articles People Will Want to Read

5 Tips for Writing Articles People Will Want to Read

awwsmm profile image Andrew (he/him) ・5 min read

Photo by Daria Shevtsova from Pexels


60-70% of links shared on social media aren't read by the person sharing them.

And even if someone does navigate to your page, you only have about 15 seconds to convince a reader that your words are worth their time.

This article outlines my five most important rules for writing content which will not only teach the reader something new, but which they will want to read.

#1 | Make It Interesting

In the marketplace of ideas, it's easy to stoop to the level of clickbait to "hook" a reader into opening up your article. But content which doesn't deliver can leave readers feeling duped or even angry.

Think of your article title like an advertising slogan. It's fine to dress it up a bit, but try not to sensationalise anything, and definitely steer clear of clickbait.

Sensationalised headline about Jeff Bezos' divorce

A sensationalised headline. (Philadelphia Inquirer)

Just like a catchy pop song, you've got to keep a person hooked, even after they've decided to give you a chance. Stick to -- and even repeat -- your most important points multiple times throughout your article.


#2 | Make It Relevant

Why should I care?

Okay, you've got my attention, so why should I spend my time reading the rest of your article?

There are different motivations for different kinds of writing. If you're documenting a straightforward solution to a problem, get to the point quickly.

"A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts."

-- William Strunk Jr., The Elements of Style

When looking for the solution to a specific problem, readers want as concise and clear an answer as possible.

But maybe you're writing a tutorial? Or documenting a cool project you've built? Make that clear at the outset, as well as throughout your writing.

  • what motivated you to write this article?
  • why did you go through all this effort to share this with others?
  • what did you learn during this process that you wish you knew at the beginning?

#3 | Make It Relatable

Build on earlier knowledge whenever possible.

Many people learn very effectively through analogy. It's why the desktop metaphor for user interfaces has stood the test of time and why skeumorphism is so popular for new technologies and devices.

Examples of skeumorphic vs. flat icons

Realistic ("skeumorphic") icons and their stylised ("flat") redesigns. (popicon.com)

But analogy can only take us so far. A rubber sheet can be used to explain the force of gravity conceptually, but eventually we need to break out our pens and paper and do some calculus.

But don't jump ahead prematurely. This is how students in a traditional classroom setting get "lost". They don't fully understand one core concept before the lecturer moves onto the next one. At that point, they have no hope of connecting the dots on their own.

Make sure that you move (not necessarily slowly, but) deliberately from one core concept to another, explaining each in enough detail that there are no "jumps" a reader has to make from one concept to another. Your job is to help them move smoothly from one stepping stone to the next.


#4 | Make It Clear, Concise, and Consistent

One of the most difficult things for newbies to any subject is jargon. And if software development has a surplus of anything, it's jargon.

What's the difference between a Python dictionary, a Ruby Hash, and a Java Map? Nothing substantial. These are all implementations of an associative array, which maps keys to values. So why the various confusing names?

It's your job as the communicator to reduce the burden of jargon on the reader. Learning a new concept is difficult enough when it's presented clearly and accurately -- it's that much more difficult when acronyms, abbreviations, and context-specific terms are left unexplained.

Comic strip about tech jargon

(JPC)

But there's a balance to be struck between clarity and conciseness.

If a reader needs to take a step back from your article because it's too high-level, you're limiting your audience, and increasing the likelihood that they'll close the tab your post is in after they've gotten an introduction somewhere else.

Even if it's short, try to provide a small introduction to your problem or topic of discussion whenever possible, and link to more detailed sources as necessary (as a "refresher"). Remove as many roadblocks as possible.

  • Always define terms with which a general reader from your target audience may not be familiar, or at least link to definitions of those terms.

  • Always use syntax highlighting (monospace) to indicate program elements, as opposed to general concepts (is this an "array" or an "Array"?).

...and finally, be a good web citizen:

  • Always provide attribution for media and quotes you use. Link back to the original source whenever possible.

#5 | Make It Memorable

"Repetition is your friend."
-- My 8th Grade German Teacher

Reinforce key concepts through repetition. Refer back to earlier definitions, provide similar-but-slightly-different examples, and provide "key concepts" reviews, when possible.

But remember to give the reader a break. Even 10x developers only have so much attention to give, and this ebbs and flows for them as much as for the next person.

Try breaking up your article with related anecdotes, and relevant pictures and diagrams. This depends on the size of your article, of course. A good rule of thumb is one piece of media, decorative block quote, or small easter egg every 5 or 6 paragraphs.

Finally, remember to reinforce your most important points at the end. There's a psychological heuristic called the Peak-end rule which says that people largely judge and remember experiences by their peak (most intense, important, or exciting moment) and by their end. You want to leave a lasting impression on the reader.


Remember:

  1. Make It Interesting

    • grab the reader's attention, but do it in an honest way
  2. Make It Relevant

    • explain your motivation, outline your purpose
  3. Make It Relatable

    • build on more familiar concepts in small steps
  4. Make It Clear, Concise, and Consistent

    • remove roadblocks to understanding
  5. Make It Memorable

Posted on Jun 19 by:

awwsmm profile

Andrew (he/him)

@awwsmm

Got a Ph.D. looking for dark matter, but not finding any. Now I code full-time. Je parle un peu français. dogs > cats

Discussion

markdown guide
 

Great article! There should be a point 0 - know your intended audience. For example, writing for beginners vs people more familiar with the topic. For the former, need to make a lot of effort to ensure that people do not need to constantly switch around googling for meanings of new terms. For the latter, it may be patronizing to do that as it will add fluff to the article.

 

Good article. Didn't read it though 🙄 Still worth an heart. ♥️

 

I don't blame you. I didn't either 😁

 

I'd rather read stuff about Bezos marriage from you honestly 😏

 

Having a nice cover image :) that is relevant to what you are writing.

 

Do you mean to say I need to improve my cover image ?

 

I did not say you specifically. It's for anyone in general.

 

It was a good read. Thanks for sharing!

 

Hi Andrew and others in the discussion,

Can you read my article once and give me some pointers ?
It's a 2 min. read. Your feedback will be very valuable to me.
dev.to/memahesh/top-5-websites-for...

Thanks in advance

 

Short and sweet.
I didn't watch the video yet but I will later on tonight.

 

I'm new to this how do I share the article helpp

 

Hit the ellipsis ... button at the bottom of the page, next to the other reactions (on mobile)