top of page
  • Stephanie Morillo

7 Common Content Marketing Mistakes Developers Make and How to Avoid Them

Read this article in Spanish/léelo en español aquí.

Developer marketing: Developers brainstorming on a whiteboard
Photo: #WOCinTech Chat

I’ve spent the better part of the last six years working really closely with developer content. What makes developer content stand out is how much of the focus is on creating artifacts that are authentic, relevant, and relatable; no matter the creator’s experience level, there’s almost always a sincere desire to share, empower, and learn from others.

But as with other forms of content, there’s a wide spectrum in terms of content quality and overall effectiveness. We’ve all seen—and undoubtedly created—content that was great and content that missed the mark. But no matter how you feel about your ability to produce content for fellow developers, there is always room for improvement.

In this post, I list seven common content marketing mistakes developers make, and how you can avoid them.

1. Not spending enough time in the editing stage

The problem:

The act of creating something new is not easy at all. We carve out time to conduct research, outline, write, and to record in order to empower others by sharing what we know.

But we don’t want to put something out in the world without having edited it for structure, grammar, and syntax. Publishing a 3,000-word blog post without reviewing it, adding headers, and other elements to break up the text, or an hourlong video as is with only light changes, will only make your content’s performance suffer. We create content so that others may engage with it; by not editing content and/or making cuts where needed, we create friction for our audience and make it difficult for them to consume what you’ve created.

As anyone with a Twitter account knows, online readers have shorter attention spans and spend far less time reading online content than print content. We scan the page; we don't read word for word. Knowing this is key to creating content that others will read.

How to avoid it:

1. Tighten up your writing: Using tools like Grammarly and Hemingway App are great ways to get you in the habit of finding places where you can tighten up your writing. They will also give you a “readability score”, which lets you know how easy-to-understand your writing is.


Another tool we shouldn’t underestimate is peer review. For longer pieces, enlist the help of a respected peer and ask them to review your content for accuracy and to provide feedback on what you can improve.

2. Break up long videos/blog posts into shorter ones: Have a blog post reaching 3,000 words that you want to publish? Break that up into two or three blog posts and turn it into a series instead. (Example: "Docker from the beginning", a multi-part blog series)

2. Not adding detailed descriptions to multimedia content

The problem:

YouTube video descriptions and podcast descriptions are all too easy to be treated as afterthoughts in the content production process. After all, you spent a lot of time recording and editing your next episode, and you trust your audience will be inspired to press play regardless.

But while descriptions might be bothersome for you, they’re important for your viewers/listeners. We use descriptions to make decisions every day, from reviewing descriptions for products we want to buy to books we might want to read.

Descriptions both tell potential viewers what your episode is about, but most importantly, entice them to tune in. It’s how you communicate what the value is to the viewer/listener.

How to avoid it:

  1. Create a template for your descriptions: You don’t have to reinvent the wheel. Create a template, or a formula, that you can drop information into like Mad Libs. (Example: Five Things on YouTube)

...And don’t forget to add links to additional resources in descriptions!

3. Not promoting content enough on social media

The problem:

We’ve all seen a high-profile developer who can promote a blog post once on social media and get a ton of engagement, but for most of us, once is not enough.

That is not to say that we should spam our followers' timelines promoting that one blog post we published yesterday, but it does mean that for those of us with fewer followers, we do need to need to do more than just one well-crafted tweet to get the views we hope for.

And with most social media platforms this is key for one reason: only a subset of our followers is checking their timelines at any point during the day. An ill-timed tweet can mean no one sees it because most people are at the office (or worse, sleeping), and it almost always means that followers who live in different time zones will miss your tweet altogether.

How to avoid it:

1. Schedule posts for various time zones (more eyeballs): Schedule one or two posts over a 24 hour period to ensure that followers in different time zones see it. Not sure who your followers are? Check out your social media analytics to determine what publish times tend to produce higher engagements.

2. Cross-promote on other platforms: Your Twitter strategy is down pat, but is that the only place where your audience is? If your audience engages with you somewhere else—like LinkedIn, for example—make sure you promote your content there, too.

4. Not checking analytics to measure performance

The problem:

Creating content without checking performance is like driving around aimlessly. Without it, you won’t know what’s working, and what you need to do to get to where you want to be.

How many views did your blog post get? What are the highest performing pieces of content you’ve published this month? Which are the lowest? What percentage of your audience found your content via organic search, and how many came through other channels? What times of day/the week do people visit your site? What topics are the highest performing? What topics aren’t you covering (but that your audience would likely want to read)? Are the keywords you’re using in your content mapped to terms that will likely increase findability in organic search?

How to avoid it:

  1. Add analytics to your personal website or blog if you haven’t already: (Resource: Learn more about the "why" behind website analytics.)

  2. Commit to checking your analytics each week and/or compiling monthly reports.

  3. Determine when your content performs the best (time of day and week).


4. Conduct a content audit: A content audit is the process of inventorying and analyzing your existing content to glean insights about what you actually have and how it's performing (among other things). Here's a great resource to walk you through conducting a content audit, step by step.

5. Not repurposing existing content for other mediums

The problem:

It’s normal and totally OK to prefer some mediums over others. Some of us prefer to write while others prefer to record screencasts; others prefer live streams to conference speaking.

While it’s neither feasible nor desirable to repurpose every piece of content across various mediums all the time—some things are medium-specific—doing so strategically will help you squeeze out more value from what you’ve created. Publishing show notes with your podcast might help you increase your listenership by attracting people who weren’t sure, or were skeptical, about the time commitment involved with tuning in. And turning parts of your talk into a blog post or a summary make it accessible to people who weren’t there or who require the use of assistive technology to consume content.

How to avoid it:

1. Turn select conference talks (in all or in part) into blog posts: Leverage your talk script or talk notes and turn it into a blog post (here's why.) (Example: I used my talk script as the basis for my talk-turned-blog post on content strategy in OSS documentation). Don't take a bunch of notes? Record yourself practicing your talk and use a service like to have it transcribed.

2. Write short show notes or "listicles" to accompany videos and/or podcasts: (Example: "Five things about Azure DevOps", a write-up accompanying a short episode of the web show "Five Things".)

6. Publishing too much content at once

The problem:

So you’ve written a blog post series or recorded a few episodes of your upcoming podcast. If you’re behind on your publishing goals, it might be tempting to dump it all at once. But publishing too much at once will overwhelm your audience and make it difficult for you to promote your content efficiently (by getting your audience excited about a new installment to begin with).

How to avoid it:

  1. Establish a publishing cadence: Should you publish once a week, twice a week, or more? The first part of the answer depends on you: how much can you realistically create in a given period of time? It’s easy to set ambitious goals for ourselves—I’ll write three new blog posts per week!—but when life gets in the way, it’s all too easy to give up.

First: set a realistic goal for yourself. “I will publish one blog post twice a month.” “I will release a new podcast episode every Thursday.” Then, set a time and date to publish using analytics to guide you. You might want to publish a new episode on a Monday morning, for example, but your stats might show that few people are likely to read it or tune in on those times.

2. Hit “schedule” and forget it! A variety of platforms, from hosted blog platforms to video sharing services and social media tools have schedule functionality; use it!

7. Not studying developer marketing

The problem:

In his book On Writing, Stephen King said, “If you want to be a writer, you must do two things above all others: read a lot and write a lot. There’s no way around these two things that I’m aware of, no shortcut.”

The same applies to content marketing; if you want to be known for producing great content for other developers, you need to study how developers and developer companies do it first.

Developer marketing is not like traditional marketing; writing for developer audiences is nothing like writing campaigns for big brands that show up on huge ads a la Mad Men. Great developer marketing is typically defined by very specific content types—primarily blogs, social media, and email newsletters—that are accessible, straightforward, concise, informational, and relevant to their audiences.

How to avoid it:

1. Follow other developers that you admire, and study their approach to marketing: Assess for yourself: what are they doing well? How do their audiences respond to what they create? What are some lessons you can learn?

2. Subscribe to developer newsletters: So many of the developer newsletters out there are high quality and have been created by professional developers with no marketing experience. What is it about these newsletters that you like?

3. Follow dev tools companies and understand what marketing assets they create: Which companies have amazing engineering blogs? What kind of content do they include in their newsletters? What types of content do they produce consistently? What do they do well?

In conclusion

Committing to creating more content for developer audiences is a great start, but to create quality and effective content, developers need to be students. Use these tips as a starting point, and leverage online resources and your own developer marketing research to help you become a better content creator and content marketer.

Like this post? Purchase The Developer's Guide to Content Creation for more content-related tips and exercises.

bottom of page