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.

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.

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.

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

   • repeat key concepts and end with a bang