21 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 the 21 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

Developers are busy and they expect no-nonsense, direct writing. 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 ten 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. Writing for developers 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, subheaders 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.

Mumble

Take a deep breath and read this aloud:

“This sentence has five words. Here are five more words. Five-word sentences are fine. But several together become monotonous. Listen to what is happening. The writing is getting boring. The sound of it drones. It’s like a stuck record. The ear demands some variety.”

— Gary Provost, 100 Ways to Improve Your Writing.

Why does it sound so dull? It’s because we read with our ears. When the inner voice is monotonous, we quickly lose interest.

Keep the text alive by varying the length of your sentences. Alternate between long and short sentences. With practice, you can even make paragraphs sing. Train the ear by reading aloud (or mumbling if you’re not alone).

Be personal

The language you use can either bring you closer to the reader or create distance.

Write using I, we, and you. Don’t be afraid to express your opinions and views. Imagine you’re speaking to a close friend and don’t write anything you wouldn’t say in a conversation.

There are instances in which rules or style guides recommend not using such pronouns. Even so, you can still maintain a friendly tone by writing in the first person for the first draft and removing it on a second pass. It may sound like extra work, but it brings warmth into otherwise dry writing.

Be positive

With this, I don’t mean that you should be a positive person (although it’s highly recommendable). I’m referring to the positive form, which says what a thing is (instead of what it isn’t).

For instance, the statement “he is usually late” is in positive form. The negative version is wordy and hard to comprehend: “he is not very often on time”. Similarly, “this idea is not without merit” can be stated more concisely as “the idea has merit”.

Use the active voice (mostly)

Most writing guides will tell you to avoid passive voice all the time. The passive voice is often associated with trying to hide something (e.g. “mistakes were made”); it also has the downside of being wordier and less vital (e.g. “the forms need to be processed”).

I believe passive voice gets a bad rap because it is easy to overuse. But the lack of subject in passive voice can be just what we need on some occasions:

• When you want to focus the attention on the action: “vaccines are being applied.”
• The subject is unknown or irrelevant: “errors were being thrown all across the dashboard.”
• When the doer of the action has already been mentioned: “the boss invited Becky to the party. I was also invited.”
• When the subject is evident from context: “she was being paid less than her colleagues.”

As you can see, passive voice has its uses. Still, most of your writing should be in the active voice.

Edit without mercy

It’s a rare occasion when a sentence comes out right on the first try. The first draft of every article is littered with lengthy, wishy-washy, cluttered sentences.

The first challenge is to cut the clutter. Remove every word which is not doing any work; they are in the way and need to go.

Don’t be discouraged if you lose half of the words in your draft while editing. The article will be all the more vigorous, and your readers will appreciate that you’re not wasting their time.

Wordy expressions come in different shapes:

• Adverbs: they all end in “-ly” (commonly, usually, personally, etc.). Rarely are they truly needed as usually more concise words are available. For instance, instead of “she smiled widely”, write “she grinned”; instead of “it’s decidedly important,” go with a more direct “it’s important”.
• Redundant words: when they repeat the noun’s meaning, e.g. a “personal opinion” is just an “opinion”.
• Unneeded prepositions: we see them all the time attached to verbs, e.g. “to free up” is often the same as “to free”.
• Wordy constructions: like saying “at the current junction” instead of “now”.
• Hedging expressions: like “maybe”, “somewhat”, “kind of”, “to a certain degree”. They weaken the text, and can make you sound timid and insecure.

Needless words are like weeds, and you have to exert tight self-control to keep them at bay. Fortunately, there are a few excellent tools to help:

• Grammarly: checks for extra words, typos, passive voice, and more.
• LanguageTool: is a less feature-rich version of Grammarly, but it supports more languages.
• Quillbot: offers automated rewriting suggestions. Good when grappling with a difficult paragraph.
• Hemingway Editor: highlights needless words and complicated sentences, offering suggestions to make the text bolder and more precise.
• Google Docs: in my experience, it has a great spell checker that catches errors none of the other tools do.

Once the clutter is controlled, it’s time to check for missing links in your reasoning and places where you branched off the topic. Each paragraph should build on the previous one without any detours. This is very careful work that demands composure. Expect the draft to undergo multiple revisions until all paragraphs perfectly line up.

Get someone else’s opinion

No matter how much you edit and revise your draft, some things will escape your attention. Show your draft to a colleague or a friend. Even strangers on a subreddit or a Discord server can offer valuable feedback.

Finding someone willing to give you an honest review is a true privilege. Should you find someone, remember that what makes a writer great is the ability to put their ego to the side and accept constructive criticism with grace.

Change the scenery

If you’re bored, people will be able to tell. Do whatever it takes to stay fresh, and don’t let your article degrade into a mechanical entry in a blog.

Here are a few things you can do to stay fresh:

• Make writing a habit: find the best time to write and make a habit of writing every day. Some people like the morning and night owls write best under the cover of darkness.
• Change the scenery: go to a cafe or the park. The library works too.
• Go for a walk: turn off the computer and do some exercise. Some of the best ideas I’ve had came to me when I wasn’t at the desk.
• Sleep on it: if you’re overwhelmed, let it rest for a few days and focus on other articles. When you come back, things will fall into place a lot faster.

Read, read, read

Writing is learned by imitation, so follow the authors you love. Pay attention to the parts that you find interesting. Keep a list of your favorite articles to read when you need some inspiration.

A wealth of knowledge about writing is waiting in books. These are my favorites:

• The Elements of Style, by William Strunk Jr,, it’s worth reading at least once a year.
• On Writing Well: The Classic Guide to Writing Nonfiction, by William Zinsser, is another must read.
• Writing to Learn, By William Zinsser.
• The Sense of Style: The Thinking Person’s Guide to Writing in the 21st Century, by Steven Pinker, provides an in-depth analysis of English grammar.
• US Usability Guide for the Web.

Conclusion

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.

Did you know that Semaphore is hiring? We’re looking for technical writers and a technical editor. Check our jobs page for more details.