13 Tips to Write Better Posts for Developers

You want to start a blog, or perhaps you already have one and want to improve your style. Maybe you’re writing documentation and struggling to make it concise and clear. Whatever the case, you have a blank screen in front of you and a head full of ideas. How do you start? How do you write a blog that other developers will enjoy?

Here are 13 things I’ve learned over my years of writing for developers.

Practice

“The only way to learn to write is to force yourself to produce a certain number of words on a regular basis.”

– William Zinsser, On Writing Well: The Classic Guide to Writing Nonfiction.

The next time you find a post you like, stop to consider what makes it so interesting. Unfailingly, you’ll see that the author is relaxed and confident, clear in making their point, and writing in their unique voice.

The good news is that writing is not a mysterious skill. You don't need to be born "good with words;" like with any craft, practice makes perfect.

There are more places to write than ever before, and no better moment to start than now. You don’t have to wait for the perfect idea. Open a text editor and write about things you love, or rant about things you hate. Reading about writing will only get you so far — the only way to get better at writing is to write.

Write in Plain English

We’re trained to believe that simpler words are not fit to explain complex concepts. This is not true. Anything can be explained in simple terms.

The trick to writing in plain English is to consistently pick the more modest alternative when faced with word choices (and we're always facing word choices):

• experiencing -> having, being

• implement -> do

• attempt -> try

• assist -> help

• refer to -> call

• individual -> person

So, instead of saying “we’ll attempt to implement changes to prevent similar problems in the future,” just write “we’ll try to fix it.” In place of “do you need assistance?”, you should write “can I help?”.

If this argument did not convince you, let me try another. Getting people to read technical documents is hard enough even for native English speakers (especially when it’s full of jargon). Now imagine how much harder it is for non-native English speakers. Plain language gives you the best chance to get your message across.

Research

Collect as much information as you can about the topic. You won’t be using every scrap of data and every little detail you find, but it will help you bolster your confidence on the subject.

You might also find a curious fact that will please readers. Never forget that a good article is always about people. Try to learn about the human side of tech: the history, the creators, and the problems they were trying to solve.

Know Your Audience

Who are you writing for? You will be your first reader, so write about what you want in the way you want. No one will read your draft as many times as you, because a good post requires a read-edit-write cycle that can take days. You won’t get far if you’re bored with your own writing.

Writing a technical post requires adjusting the context for the intended audience. For example, if you’re writing about React components, you can assume that the reader will know how to use Git, and has competence in JavaScript and Node. That’s your starting point.

Conversely, suppose you’re writing about taking the first steps on Git, you can’t take for granted that the reader is familiar with version control. So, you’ll need to provide some background before diving into the main topic.

Make the Post Skimmable

Since 1994, Jakob Nielsen and John Morkes have been conducting studies to learn how people read online. Their conclusion, which remains true, is that readers rarely read the whole page.

Online readers are active. They like to scan and skim, picking the information they need. Most readers will read only 20% of the words in a given article.

The researchers tried several ways of improving the reader experience. They found that people understood and retained more information by making the article scannable.

So, help your the readers find the information they need by:

• Writing short (8 words or less) and interesting headers that tell a story. Don’t go deeper than H2 or H3.

• Write short paragraphs of less than 5 lines.

• Use bold or italic fonts to emphasize important parts of your text.

• Separate sections with plenty of whitespace.

• State the idea behind each paragraph in the first sentence.

Pick a Good Headline

Sometimes the title is all we have. Sometimes we have all but the title. Whatever the case, your title must do a lot of work. It has to pull the reader in while giving a good idea of what the article is about. People are exposed to dozens of articles every hour demanding their attention. How is yours different from the rest?

A title either works or it doesn’t. Unfortunately, there’s no algorithm to find the best title, only a few heuristics:

• Have it include a keyword or topic phrase that describes what the article is about.

• Keep it under 10 words.

• Remove prepositions (a, of, the, and) where you can.

• Include a number in the title if possible.

• Capitalize your title.

• Use an online headline analyzer to tweak the impact of your title.

Focus on One Thing

The reader should get one (and only one) thing from your post. Your first job is to decide what the article is really about. Read what you’ve written and look for where you’ve drifted off the mark; one of the painful realities of writing is having to cut interesting parts that are not relevant.

It can take a few false starts until you find what you want to say. For example, the first version of this very draft had too many details about English usage that didn’t have a whole lot to do with developers, so I cut them out.

I like to keep all the relevant information at the top of my draft, where I can see it every time I start working. This is the template I use:

• This article is about: explaining Git basics

• Article format: list of most used Git commands

• Audience: junior developers with no previous version control experience

• Possible titles:

  • Getting Started With Git

  • Git First Steps

  • Git for Beginners

Start Strong

The lead (or lede) is the leading paragraph in your post. The first sentence should carry the reader to the second, the second one to the third, and so on. If the lead is not strong, the article won’t draw readers in.

Every article is different, so you’ll have to find a lead that works for each case. Here are a few ideas to get you started:

• A personal story

• A curious or surprising fact

• An interesting quote

• Breaking expectations

• A paradoxical or counterintuitive statement

• How the reader benefits from the content

Have an Ending

Not much to elaborate on here, except that a post should have an ending, even if it is just a single sentence, to mark that you’re done.

Take this chance to reinforce your message or link to other relevant posts. Circling back to the lead will give the reader a pleasant feeling of closure.

Sharpen Your Paragraphs

A paragraph should represent one (and only one) idea or topic. A typical paragraph is comprised of three parts:

1. Introduction: a sentence introduces the topic of the paragraph.

   “TypeScript is a programming language developed by Microsoft.”

2. Explanation/argumentation: the topic is developed with examples, counterexamples, and supporting arguments.

   “… It extends JavaScript by adding optional static typing to the language.”

3. Reaffirmation: a final sentence closes the idea or transitions to the next one. The last sentence tends to linger in the mind of the reader, making it the best place to make an important point.

   “… All JavaScript is also valid TypeScript, allowing developers to adopt the new language gradually.”

Never introduce two ideas in the same paragraph. Instead, take your time to develop them separately.

Regarding length: it’s best to keep the paragraph’s length between one and six sentences and below five lines.

Avoid the Wall of Text

You have an advantage over the vast majority of writers in history: you have near-unlimited possibilities for non-text elements such as graphics, animations, or diagrams. And creating interesting graphics has never been so easy. A picture can set the mood without a painstakingly-drafted paragraph. A chart can save you a lot of typing. Both provide respite to the reader and give something interesting to look at.

Never go for longer than three paragraphs without using one or more of the following:

• Pictures

• Diagrams or charts

• Code snippets

• Lists

• Headings

• Tables

Make Foolproof Tutorials

The tutorial is the most laborious type of technical writing. The instructions must be clear, unambiguous, and traverse the most direct path to the objective. Writing a tutorial is like writing a program, except the platform is a human. You’re giving instructions, but you don’t get the benefit of error messages.

Count on readers missing steps and not paying attention when commands fail. It’s not their fault. Some degree of trial and error is inevitable when trying to learn something new. Ground them by planting reality checks within the tutorial, e.g., “at this point, your database should be running. You can check the connection with the following command …”

There’s also a bit of experimentation on your side. You must look for the most foolproof alternative for achieving each task. Commands that can be copied and pasted directly tend to work best — but may need some tools to be installed first. In any case, try to avoid having readers edit commands by hand.

# instead of this
$ docker login -u YOUR_USERNAME -p YOUR_PASSWORD SERVER_NAME

# set the values separately
$ export username="YOUR USERNAME"
$ export password="YOUR PASSWORD"
$ export server="SERVER NAME"

# now you can copy and paste this command directly
$ docker login -u "$username" -p "$password" "$server"

Triple check every step and, if possible, get someone else to test drive the tutorial before publishing.

Minding SEO

Write a good article and people will come, but there’s no harm in getting a little help from Google. Search Engine Optimization (SEO) is a set of practices for ranking higher in search results. Good SEO standing will drive organic traffic to your posts, increasing your exposure.

This is not a complete guide by any means, but with a few tweaks you can direct more eyes to your post:

• Pick some keywords that fit well with your post. You can search for keywords using ahrefs.com and Google keyword planner.

• Pick a good title: bonus points if it contains relevant keywords.

• Sprinkle keywords throughout your post: the lead, subheads, and within paragraphs.

• Use ALT tags in your images.

• Add metadata to the post.

• If you manage your own website, ensure that it has good performance.

Closing Thoughts

I've written about writing in the past, so there are plenty more tips to keep in mind while writing.

The moment you open a text editor and start typing, you’re a writer. You can write for fun, to learn, or even for therapy. You can also make a living or earn some side money with writing.

Whatever the case, I hope these tips help you write posts developers (and non-developers) will enjoy.