21 Tips to Write Better Posts for Developers

Practice

Write in plain English

  • experiencing -> having, being
  • implement -> do
  • attempt -> try
  • assist -> help
  • refer to -> call
  • individual -> person

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.

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.

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.

  • 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?

  • 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.

  • 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.

  • 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.

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.”

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.

  • 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.

# 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"

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.

  • 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:

Be personal

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

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).

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”).

  • 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.”

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.

  • 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.
  • 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.

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.

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.

  • 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.

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.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Semaphore

Semaphore

Supporting developers with insights and tutorials on delivering good software. · https://semaphoreci.com