The Developer Voice Guide: How To Write Articles Engineers Want To Read

Want to write an article that speaks authentically to engineers and lets you share your know-how? Get started with this guide. 💪

What you’ll find inside:

1. Know yourself
2. Know your audience
3. Nine(9) practical tips to make your article more engaging
4. Edit the article
5. Show your article to someone else
6. Writing comes with day-2 operations, too!

Bonus: final checklist

1 - Know yourself: Understand your motivation & keep your spirit up throughout the process

Before setting down to write an article, ask yourself: what’s in it for me?

Your end goal might be personal development and sharing your expertise with others. Writing helps here because it’s a forced way to think more clearly. Early Facebook employee Andrew “Boz” Bosworth shared a similar thought in Writing is thinking:

“Even when I write for my own benefit, it is undoubtedly a bonus that at the end I have a document which I can easily share to invite critiques or enlist support. I know of no more scalable way to engage a large audience than the written word.”

Having a clear idea of your motivation is a great first step — and something that will keep you going throughout the process, especially when other things take priority over writing, and coming back to it will get hard.

2 — Know your audience: Who’s at the receiving end of your article?

Who are you writing for? What is the level of expertise in the topic? You may assume that they have some level of technical knowledge, but not everyone might be familiar with all the terms (this is where a glossary helps!).

Having a clear picture of the reader will help you explain the subject matter better. To clarify it, ask these questions before you sit down to write:

• Do they already know your product?
• How does the reader feel about the topic before reading the article?
• How should the reader feel about the topic after reading the article?

3 — 9 practical tips to make your article more engaging

3.1. Structure your article for clarity

An article meant to engage software engineers is not the best place for unleashing your inner creativity. 😉

What you’re looking to do here is to get your point across in the least painful way for readers.

That’s why structuring your article is so important — it helps readers to follow your thoughts.

Use this structure to help readers understand your point:

• Start your article with an introduction — set the context, say why the problem you’re solving is important, use examples from your experience, and instantly communicate the value of the article (what readers will get from reading it).
• Follow with the body text — make sure to divide the text with headings (H2, H3, H4, etc.) to make it scannable.
• End with a concluding section — it can be a summary of what you’ve done or — even better — broader conclusions about the field or predictions for the future use of some tool. What is the takeaway of the piece? What is the one, or two things I should leave the reader with?

3.2. Use active voice over passive voice

Consider this example:

This feature can be used to do task X. vs. You can use this feature for task X.

The second sentence reads much better, doesn’t it?

This is the power of active voice over passive voice. Using it makes a massive difference in the readability of your article.

Plus, it helps you sound less like a robot and more like a human being — this is how we actually talk to each other. 😊

3.3. Keep it short and sweet

Explain your argument step by step without taking more time than necessary to dwell on each of the steps.

Use short sentences of 25–30 words per sentence max to help your readers keep track of your thoughts.

Keep it simple to get your point across faster (and with less cognitive effort required from readers). Replace complex expressions with simpler ones — for example, use instead of utilize.

3.4. Educate without condescension

In most articles out there, engineers try to explain the merits of their approach/solution. This creates a trap: you might end up sounding admonishing or condescending.

Instead, use a friendly, inclusive, and supportive tone. You don’t want to alienate readers or make them question their skills or knowledge. 😊

Mason Egger, an ex-developer advocate and community author at DigitalOcean known for its amazing docs, said even words like “simple” or “easy” are tricky — what is ‘simple’ or ‘easy’ to someone might be challenging to someone else:

“You’d be surprised how many people get turned off by seeing something that other people tell them is simple, and then it’s not simple to them. It turns them off the entire project.”

Here are some more useful articles on this point:

• https://www.knowledgeowl.com/blog/posts/dont-say-simply-jim-fisher/
• https://www.setcorrect.com/portfolio/work14/
• https://css-tricks.com/words-avoid-educational-writing/

Note: A snarky tone can help you stand out when backed by deep subject expertise and empathy for readers. Here’s an excerpt from Corey Quinn’s newsletter that illustrates this:

“Amazon EMR Serverless cost estimator — If there’s one thing customers love, it’s having to jump through complex hoops to predict what their cloud cost is going to be.”

3.5. Use tech jargon with care

Tech jargon is great — it helps you to communicate with readers better and creates a sense that you all belong to one community of data practitioners.

But too much jargon or complex techy words might have an alienating effect on readers. So, avoid packing your sentences with terms others might have trouble understanding. Your goal is to get your point across, not sound smart. 😉

And if you use an acronym like ML, make sure to write out the full name the first time you use it.

3.6. Be inclusive

You never know who your reader is. When speaking about an abstract person like a developer, use gender-neutral words and pronouns: they instead of he/she.

Stick to second-person pronouns like “you.”

3.7. Use examples and analogies

Use analogies to describe more complex concepts.

Don’t tell, but show instead. A picture says a thousand words. Including examples helps to explain things. Use illustrations, screenshots, images, gifs, code snippets, etc.

3.8. Use text formatting readers are used to

This helps them to navigate the text and quickly check if your article answers their questions. If you bury it in a long paragraph of text, the chances someone will take the time to dig it up are literally zero. The readers will just move to the next resource on the topic and never look back.

Here are a few things you can do:

• Create a visual hierarchy to help people quickly find the information they need.
• Use text formatting to create levels of headings (such as H1 to H6 headings in HTML).
• Add a TL;DR section or summary at the beginning of your article.
• And don’t forget about the table of contents!

3.9. Make it FUN (edutainment)

Sure, you’re writing to share your knowledge and get your point across. But a little fun never goes amiss.

We all love jokes, memes, and emojis. Include them in your article to make it more engaging. Don’t over-use them, though 😀

4. Edit the article to make it more concise

Once a draft is ready, it’s time to edit it! Editing is about making this piece more digestible for the reader:

• Go through the article to make sentences shorter and clearer. You can use tools like Hemingway here to make your article easier to read.
• Catch spelling and grammar mistakes using a tool like Grammarly.
• It’s ok to cut out sections that make the article boring or too long. You can always split it into parts — part 1 and part 2.

5. Show your article to someone else

Getting a second pair of eyeballs to scan your article never hurts. 👀

Share your draft with a peer to get their feedback and check that your argument flow is clear. You might even get to see the problem from a new perspective and add the pieces missing in your argument to make it stronger.

6. Writing comes with day-2 operations, too!

Once your article has been published, it might receive amplification on social from readers. Be present, and don’t hesitate to reply!

If they suggest changes or identify typos, don’t get discouraged — applying these fixes will help you write better.

Bonus: Final checklist

So, you wrote an article? Amazing! 🎉

Take a look at this checklist to make sure that your article ticks all the boxes for maximum value:

1. Does the title clearly reflect what this article is about?
2. Does the introduction of your article state the goal of this article and help readers understand whether it’s what they were looking for?
3. Did you include a table of contents or a TL;DR section?
4. Does your article have a clear structure?
5. Does your article have a clear visual hierarchy?
6. Does your article include examples? For instance, fragments of code, images, illustrations, gifs, screenshots?
7. Did you answer all the potential questions developers might ask about this topic?
8. Did you add all the relevant internal and external links to resources that might be useful for readers?
9. Is the content long enough to explain the topic exhaustively but not too long? Does your article go outside of its scope anywhere?
10. Does your article include details that can easily change? This might make it outdated soon. To avoid this, link to more up-to-date external sources instead of replicating their content.

This is it!

If you enjoyed this story, please click the 👏 button. Feel free to leave a comment below.

Follow me here, or here for more posts about Machine Learning, Big data, Technical writing and software engineers nonsense. Cheers!