DEV Community

Cover image for 5 Tips for Writing Articles People Will Want to Read
Andrew (he/him)
Andrew (he/him)

Posted on

5 Tips for Writing Articles People Will Want to 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

Top comments (17)

Collapse
 
damcosset profile image
Damien Cosset

Good article. Didn't read it though πŸ™„ Still worth an heart. β™₯️

Collapse
 
awwsmm profile image
Andrew (he/him)

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

Collapse
 
damcosset profile image
Damien Cosset

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

Collapse
 
delta456 profile image
Swastik Baranwal

It was a good read. Thanks for sharing!

Collapse
 
steelwolf180 profile image
Max Ong Zong Bao

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

Collapse
 
memahesh profile image
Medam Mahesh

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

Collapse
 
steelwolf180 profile image
Max Ong Zong Bao

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

Thread Thread
 
memahesh profile image
Medam Mahesh

Got it, thanks.

Collapse
 
rrampage profile image
Raunak Ramakrishnan • Edited

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.

Collapse
 
waylonwalker profile image
Waylon Walker • Edited

One tip I have for about anyone who asks is to have a good layout and flow. I think this can fit under a few of your bullets. If I am intrigued by your title and click your article and cannot figure out what it's about in 15s I'm out(unless it's a topic I'm deeply interested in).

If I am loosely interested in the topic and see a wall of text, no headings, quotes, bold, paragraphs, etc I'm out.

If I'm loosely interested, but see well laid out sections, I start by reading section titles, then decide if I want the whole thing or certain sections. If certain sections were really good, you got me and I go back for the rest.

If I make it that far, and I really enjoyed it, it's likely that you get β€οΈπŸ¦„πŸ·οΈ πŸ’¬, a follow and tweet.

If it didn't look interesting from the beginning, I bounced and you got nothing.

Collapse
 
awwsmm profile image
Andrew (he/him)

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

Collapse
 
memahesh profile image
Medam Mahesh • Edited

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

Collapse
 
functional_js profile image
Functional Javascript

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

Collapse
 
sumukhesh profile image
Sumukhesh

Great points.
It will help alot of beginner bloggers like me to fine tune the content they want to post.
Cheers !!πŸ˜‡

Collapse
 
waylonwalker profile image
Waylon Walker

You can also just share the url

Some comments may only be visible to logged-in visitors. Sign in to view all comments.