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

Know your audience

Make the post skimmable

  • 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

  • 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

  • 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

  • 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

Sharpen your paragraphs

  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

  • Pictures
  • Diagrams or charts
  • Code snippets
  • Lists
  • Headings
  • Tables

Make foolproof tutorials

# 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

  • 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

Be personal

Be positive

Use the active voice (mostly)

  • 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

  • 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

Change the scenery

  • 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

Conclusion

--

--

--

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

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Who else out there is tired of click-fucking-bait?

3 Ways to Always Have Ideas When You Need Them

A balance between idaf and child-like wonder.

Redefining Success as an Author

The Global Lockdown Proving Out To Be A Writer’s Paradise

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

More from Medium

High-Level vs Low-Level

Technical books that made me a better Software Engineer

10 Interview Questions that land me an offer as Project Manager

Power grid graph

How to Build a Software Engineer Career Ladder (Example)