5 Tips for Writing Articles People Will Want to Read
Tags: writing, beginners, tutorial
Published: 2020-06-19 12:44:28

> _Photo by [Daria Shevtsova](https://www.pexels.com/@daria?utm_content=attributionCopyText&utm_medium=referral&utm_source=pexels) from [Pexels](https://www.pexels.com/photo/toddler-reading-book-1257105/?utm_content=attributionCopyText&utm_medium=referral&utm_source=pexels)_

---

[__60-70%__](https://www.washingtonpost.com/news/the-intersect/wp/2016/06/16/six-in-10-of-you-will-share-this-link-without-reading-it-according-to-a-new-and-depressing-study/) 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](https://www.crazyegg.com/blog/why-users-leave-a-website/) 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](https://bit.ly/30XNuIk) 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](https://en.wikipedia.org/wiki/Sensationalism) anything, and definitely steer clear of clickbait.

<figure>
<img alt="Sensationalised headline about Jeff Bezos' divorce" src="https://www.inquirer.com/resizer/ifba685c1J2XKjxlcE-0Xo8G8LE=/1400x932/smart/arc-anglerfish-arc2-prod-pmn.s3.amazonaws.com/public/ATWUM4GAS5BXLBJBHANNVRWLRA.jpg"></img>
<figcaption>A sensationalised headline. (<a href="https://www.inquirer.com/news/national-enquirer-jeff-bezos-extortion-history-trump-20190208.html">Philadelphia Inquirer</a>)</figcaption>
</figure>

Just like [a catchy pop song](https://www.youtube.com/watch?v=pdz5kCaCRFM), 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_](https://www.walkersands.com/get-to-the-point-writing-succinctly/)

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](https://en.wikipedia.org/wiki/Desktop_metaphor) for user interfaces has stood the test of time and why [skeumorphism](https://en.wikipedia.org/wiki/Skeuomorph) is so popular for new technologies and devices.

<figure>
<img alt="Examples of skeumorphic vs. flat icons" src="https://cdn.shopify.com/s/files/1/0743/4995/articles/SkeuM-vs-FlatIcons.jpg?v=1493680581"></img>
<figcaption>Realistic ("skeumorphic") icons and their stylised ("flat") redesigns. (<a href="https://www.popicon.com/blogs/iconography/is-skeuomorphism-really-dead">popicon.com</a>)</figcaption>
</figure>

But analogy can only take us so far. A [rubber sheet](https://www.youtube.com/watch?v=MTY1Kje0yLg) 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_](https://en.wikipedia.org/wiki/Associative_array#Language_support), 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.

<figure>
<img alt="Comic strip about tech jargon" src="https://thinkjpc.com/wp-content/uploads/2017/04/jargon.png"></img>
<figcaption>(<a href="https://thinkjpc.com/content/can-use-orwells-rules-writing-make-copy-readable/">JPC</a>)</figcaption>
</figure>

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](https://en.wikipedia.org/wiki/Peak%E2%80%93end_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__
    - repeat key concepts and [end with a bang](shorturl.at/ghwT2)