Here are several examples that resonate with a developer audience, and tips for how you can successfully execute technical writing.
I’ve been working on a blog project for Managers in Tech for a few months now — so the concept of writing for a technical audience has been top-of-mind. Regardless of what you’re writing about, the goal is to offer data-driven details and concise explanations. Strive to do the work and research so that readers are able to consume the content however they choose — whether it’s reading line by line or skimming for keywords.
Here’s a summary of key tips and tricks:
- Content should be fact-driven and have a logical, flowing structure.
- Use short sentences and bullet points to make the content dense but simple.
- Break up large paragraphs. Place key ideas into bullet points, which can help drive home important points and improve retention.
- Don’t rule out realistic storytelling — such as an opinion piece or a case study. Talk about authentic experiences.
- Back up statements with credible references. Don’t make sweeping statements or generalizations and be sure to use plenty of examples.
- Diagrams and visual elements are a necessity.
Read on if you want to learn more!
While the result of technical writing is strong and succinct, the process can be the opposite. I discovered some great writing samples that I wanted to share with you.
Example #1: re:Work’s blog on 1:1 meetings
There’s nothing harder to read than an article that has long paragraphs and no headers. The simple layout in this blog post makes this piece easy to skim, which is how most developers consume content.
A quick intro followed by clear headers makes it feel like you’re reading instructions. I also like how bullets points are used instead of complete sentences — this helps with the overall flow.
- Content should be succinct — eliminate “fluff,” like unnecessary words or phrases. Don’t overload readers with information or complex ideas when you don’t have to.
- A strong call-to-action is crucial. Ask yourself: “what’s the goal of the reader? To complete a task? To research a topic?”
Example #2: dein.fr’s blog on code review
Sometimes the simplest things are the most profound. This piece is the perfect example. The bullet points reference the diagram at the top — and that’s it! It’s clear that they supplement each other, removing the need for transitional copy like an intro.
I also like how a series of questions are used to highlight what’s important in code review. It feels like more of a checklist than anything else. Once again, super easy to scan.
- Don’t be afraid to put out dense content that’s straightforward. Developers want substance in what they read.
- Look for ways to engage the audience, like having a space for them to comment or share ideas. In this case, the post links to Reddit, where plenty of people chose to provide feedback.
Example #3: Localytics Eng blog on software management
Some of you will be surprised to learn that developers are super creative. That’s why I appreciate this piece.
The unique layout is just like a recipe — complete with instructions, resources, and expected outcomes. I love how impactful this feels.
- Experiment with how you organize content. Is there a fun metaphor that you can incorporate? This will help your piece stand out.
- Only include credible resources. This way it’s clear you did meaningful research, and can back up what you’re saying.
Example #4: Cate’s blog on 1:1 meetings
There will be some cases where long paragraphs work in your favor. I think it makes sense to include context when you’re writing about an opinion or experience.
My favorite thing about this article is how it reads like a diary entry. The author uses first person phrases like “from my experience,” and “as a new manager.” Developers prefer to read content by individuals — not companies — because it’s less branded.
- Share glimpses of your experience as it relates to the topic. Remember that you can be direct without sacrificing complete sentences.
- Use the first person to make readers feel like they are gaining advice from someone who has had credible experiences.
I hope you found this article helpful. Use it as a guide when writing content for a technical audience. There’s always room to improve readership — a common goal for many of us.
For those of you interested in reading the best piece of explanatory technical content I’ve ever read as a tech guy, check out Trevor Summer’s tweetstorm about the #Boeing737Max crash. This pretty much sums up all of the tips above — and shows that impactful content can take various forms.
Let me know your thoughts in the comments below!