The DevTool Messaging Guide
Step-by-step advice on presenting your service to engineers
Developer marketing is all about helping visitors understand if your tool is the right fit. But, many sites include useless information and miss out key details.
They promise vague results without explaining how they achieve them…
They fail to address common concerns preventing the sale…
They don’t explain the benefits of a pioneering feature…
It’s easy to fall into these traps, especially if you jumped straight into writing full copy. You end up including whichever feature or benefit comes to mind as you write and miss out key details.
We’ll prepare each messaging element before combining them
It’s the writing equivalent of making up a recipe as you go, suddenly deciding you need a vegetable and quickly chopping whatever is at hand. You might still cook a tasty dinner, but a small amount of prep would improve the results.
Instead let’s be like professional chefs, thinking through which ingredients would best suit the dish and preparing them all in advance.
Doubling conversions with solid messaging
We’re going to look at first refining each messaging element. You will gradually define the necessary points and how to frame them, before building the outline and finally creating compelling content. The steps are:
Part 1: Pain points and alternatives
Part 2: Awareness and framing
Part 3: Benefits and outcomes
Part 4: Objections and skepticism
Part 5: Outlining and creating content
It won’t be the usual catch-all definitions. You’ll get detailed steps to help you avoid bland statements and make sure each is truly relevant to your audience.
The quick route to a beige website, I promise there’s no mad libs in this guide.
All of these techniques are based on my years of refining the messaging for clients. I’ll admit that the process takes time to do well, but it typically gives a 2x boost to conversions so I reckon it’s worth it.
Context is everything. You would never try to sell Python for Dummies to a senior engineer. Yet, companies make context mistakes all the time.
Before we even think about pain points, let’s define the situation causing the issues. After that we can use lifecycles as a prompt to generate pain points, then refine what’s causing headaches.
Ok, let’s get started!
Define the customer scenario
DevTools are usually replacing an existing workflow step. Your prospects already have a way to track bugs, deploy code or manage APIs.
That means the pain point is often in the specific way they are currently handling things.
For example, an autoscaler isn’t just solving app slowdowns since prospects are already fixing them manually. The pain point is the slowdown alerts in the middle of dinner.
That’s why the very first step of defining your DevTool messaging is acknowledging the current way of doing things. The alternative you are replacing can be
Something barely optimized or handled manually
Using the DIY or free OS option
An established and relevant tool
For each one, the pain points become the issues with that current way of working, such as the headaches from outgrowing an OS tool.
I’d say this is the most important step for defining your ideal prospects. Even if you have direct competitors, you need to acknowledge if potential users are actually comparing your service to just handling it manually.
Step 1 is always to consider the buyer scenario
If you know your users well, then the answer to this should be obvious. Just try not to hedge your bets, as each piece of content can only speak to one group
Pain points through the lifecycle
The challenge is now to define the pain points in the relevant user scenario. Instead of doing it free-form, use the product lifecycle as a prompt.
(Note: this also includes the workflow of handling the challenge manually)
Start by writing out the pain points at each stage of carrying out the work. There can be potential headaches during:
Set up and integration
Normal daily use
Maintenance
Outcomes and results
Troubleshooting issues
Don’t worry if some are irrelevant or you don’t solve them all as we won’t use every pain point in your messaging. The point is to explore all the options.
Now the challenge is getting them as specific as possible by zooming in on the issues. So let’s refine them through two methods.
Refining pain points: Expectations vs Reality
Try comparing how a process is expected to work vs how it typically plays out.
For example, here’s a comparison of the expected vs actual git workflow that I drew for a client. It helped us to easily pull out pain points in the process.
An ideal vs reality for git workflows reveals specific pain points
Repeat this expectation vs reality for each step of the devtool if relevant. Does it reveal more headaches in diagnosing errors? How about maintaining integrations?
Refining Pain Points: Root Cause Analysis
You can get specific through a variation of Root Cause Analysis. You’ve probably heard of RCA through the 5 Whys method for uncovering what caused a problem.
Apply this technique to each of your pain points. Ask yourself why it’s a problem or what makes it so annoying.
Let’s take rebasing branches as an example. They’re annoying, but why? We can pick out two specific points:
The typical rebase race is an annoying distraction
A broken main branch interrupts the whole team
It will probably only be relevant to go one or two levels deeper. You don’t need to define extremely obvious issues like why work interruptions are a pain point.
Note: Pricing is a risky pain point
I would generally caution against pricing as a key pain point.
Even if you save a company thousands a month, it might only be 0.01% of their revenue. That saving can even be balanced against other factors such as migration headaches and platform risk.
For example, Heroku is more expensive than AWS. Yet saving DevOps staffing costs and headaches make the price worth it to users. So, I wouldn’t recommend putting all your eggs in that basket.
Example: Ditching the pain points of established tools
Linear is a modern issue tracker that’s solving specific issues with the old options.
Losing track of issues isn’t really the problem they’re addressing, as prospects already handle that with tools such as Jira. Instead, the pain points are the usability frustrations with other issue trackers.
A great example from Linear of addressing usability issues
Their first section does a great job of addressing these usability pain points.
They don’t just say “it’s easy to use”, as that never convinces anyone. Instead, it has three concrete ways that it overcomes issues around speed and clunky UIs.
Part 1: Pain points and alternatives
Part 2: Awareness and framing
Do your prospects even know they have a problem? Or that the issue can be solved?
You inevitably spend countless hours thinking about how your tool helps developers and the pain points it addresses. But, we can’t assume that the issues are obvious to your prospects.
That’s why we need to stop to consider their awareness level.
Unaware, ignoring, or solving
You know about their pain points and that a solution exists, but do they?
For example, users might be unaware of a potential security flaw in their back end. Talking to those users requires a more educational approach than people actively looking to solve a problem.
That’s why stages of awareness is key. It’s a classic copywriting concept I’ve adapted from Eugene Schwartz.
Take a moment to consider how aware your prospects are of each pain point.
Unaware - Doesn’t really know anything is wrong, potentially overlooking symptoms
Ignoring - Knows about the problem but doesn’t see fixing it as a priority
Solving - Wants to fix the problem and is looking for solutions
Most marketing defaults to writing for the Solving group. Classic “don’t sell the drill, sell the hole” advice plays into this, assuming that people already want the outcome. But, it’s not always the case.
Awareness can even vary between pain points.
Think through the key pain points from the previous section. Are there some issues they’re looking to solve, while they’ve accepted others as inevitable? Or maybe they’re looking to solve the big picture issue such as an app being slow, but are unaware of the specific problem causing it.
Go through your list of pain points and mark down the awareness level around each one.
With that in mind, we can think about how to talk about pain points for the different groups.
Framing for Solving
People seeking a solution are the easiest awareness level to write for. You’ll need to show them how your product will solve their issues, addressing each of the specific pain points.
But, don’t get complacent.
There might be specific details that they have been ignoring, or knock-on effects that they are unaware of.
Framing for Ignoring
Have you ever had a friend complain about a toothache for weeks but they haven’t gone to the dentist? It’s a great example of ignoring an obvious pain point.
The ignoring group has two subtypes.
Some people know that solutions exist but aren’t getting around to fixing it. You’ll need to overcome their reasons for putting it off (we’ll discuss that in Part 4) or provide results to act as motivation.
The easier group is people who have just accepted a headache as inevitable. Once you have pointed out that solutions exist they should be enthusiastic.
Framing for Unaware
The Unaware group is the most difficult group to write for. You’ll need to take them from not realizing there’s an issue, to generally wanting to solve it, to wanting to solve it specifically with your product.
Take website messaging for example. I need to write a 3,000 word guide to help people be aware that their messaging is missing the mark.
The unaware group needs an educational approach to help them notice their own blind spots. This could be through tools, calculators, or articles that pick out the issue.
Example: Revealing website blind spots
Pingdom’s free speed test is a fantastic way of raising the problem awareness in web developers.
Instead of simply telling developers to buy their product, here the webdevs can see the specific issues Pingdom is catching. By analyzing the website performance, they move people further up the awareness scale towards seeking a solution.
So now we have problems and whether we can talk about solutions, next let’s look at how big picture to go when discussing results.
Part 3: Benefits and outcomes
I suspect that when people say “developers hate marketing”, they mostly mean overhyped promises. In particular, claims of vague top levels benefits.
Thanks guys, that’s so insightful. Really helping me make an informed decision…
It’s tempting to completely ditch benefits, but I think that’s going too far in the other direction.
Instead, view benefits as a balancing act. You want to avoid pointing out the obvious but you still need to highlight value where necessary.
Think in terms of Benefit Layers
It’s true that some features don’t require benefits. Developers don’t need you to tell them why a faster CPU is a good idea, they will just want the specs.
But what if you have a new or unique feature? Sometimes the implications aren’t obvious, in which case you need to point out the benefits.
This is why each feature requires a different Benefit Layer. These are:
Feature-only - Skip the benefit if it’s obvious
Direct benefit - Use if the immediate effect needs pointing out
Knock-on benefit - Use if the bigger implications are unclear
Top-level benefit - Avoid unless you’re a category leader
It can be tempting to pitch the top-level benefit to try and increase the perceived value. But, that leads to the overused “Ship Code Faster” headlines which don’t tell your reader anything helpful.
Let’s quickly go through each one.
Feature-only
There are various features where the benefit isn’t needed. Upgrading specifications is a good example, where you don’t need to describe the benefit of better stats like a higher data rate.
It is also relevant for a table-stakes feature, where you only need to reassure them that you have the ability such as relevant integrations.
Direct benefit
Mentioning the direct benefit is a fairly safe bet. Some readers might think you’re over-explaining but some might need the implications pointed out.
You’ll see this a lot in the GET [BENEFIT] FROM [FEATURE] style of writing, where an outcome is described followed by a specific feature.
Knock-on benefit
Moving into the bigger picture gets riskier. It’s valid if your feature is something very unusual, such as if it’s augmenting a process in a way that’s not obviously beneficial.
The risk is having an unclear cause and effect which sounds like an empty promise. You need to draw the dots between your big promise and how your feature delivers that.
Top level benefit
I would generally avoid going too big picture. Yes, your feature might mean fewer alerts, which means fewer interruptions, which means more code shipped...but “ship more code” will always feel vague and unhelpful.
If you’re the market leader where everyone knows what you can do, you can get away with this. Otherwise, don’t.
Example: Over-explaining stats
CircleCI are a popular CI tool. Most of their site is solid, but this jumped out as too salesy.
The Top Level Benefit is unnecessary here. Developers know why faster builds are desirable without it being overexplained.
I would write this with a Direct Benefit such as:
It might feel unexciting to write, but there’s nothing wrong with keeping it simple. I would stay at the feature level and use the body copy to detail how they achieve faster build times.
We’ve almost got our pieces laid out now, there’s just one more crucial element. Objections.
Part 4: Objections and skepticism
If you use all the ideas so far you’ll get their interest, but not necessarily the signup.
That’s because even if your solution is intriguing, they will still have objections. These are the various unknowns that will make them hesitate, wondering if it’s worth the risk.
What’s stopping them?
There are various reasons why a developer might be interested in your product but not go for it. Try to think through all the reasons they wouldn’t sign up. Common objections include:
Learning required - Not wanting to learn their way around yet another interface and set of terms
Integrations/compatibility - Feeling unsure if you easily support their specific stack
Lock-in - Worrying about what happens if you fold or they outgrow you and the migration headache
Team buy-in - Fear of resistance from the rest of their team either up or down the chain
Cost - Not wanting to pay yet another monthly subscription
Failing to address key objections is a quick way to lose the sale, so we’ll need to plan appropriately.
Does anyone get excited about learning to navigate yet another UI?!
Define your counterpoints
Go through and think through how you’d counter each objection.
You need to make your answers as concrete as possible, not bland statements like “easy to use”. Developers are skeptical and assume that vague promises are empty fluff. Think of details such as:
Do you have metrics to prove your point?
Are there aspects of a feature you can mention?
How do you solve edge cases?
Are there docs that would reassure them?
Let’s take scalability as a common worry. Saying “we’re highly scalable” is meaningless. Instead, giving a figure such as “proven to scale to over 1,000,000 data points per second” as concrete evidence.
Example: showing the minimal learning curve
One of my clients sold an autoscaler. The product feels like it should be a no-brainer, reducing both the server costs and amount of interruptions from alerts. Yet, they weren’t getting as many sales as they hoped for.
We identified usability concerns as a key objection. So, we created this section to show how easy it is to use. It gives a specific usability claim, naming and showing the four sliders that define the app.
With those counter objections done we now have our elements all prepared!
Part 5: Outlining and creating content
Well done, we now have all of our pieces!
We can now pick key details with intention and consider how to arrange them. This helps us avoid causing confusion by mixing unrelated points together.
The body copy must always support the subheading
Start with bullet points
I would highly recommend starting with bullet points to avoid getting distracted by wording choices.
My format for each section is usually
Subheading/section idea
Detail 1
Detail 2
(Maybe) Detail 3
The bulleted details could include aspects of how you’ll deliver the promise, results to prove the benefit, or elaborating on the pain point. We’ll go into that in a moment, but first let’s focus on the overall flow.
Here are two methods I use to decide the relevant elements for the page and create a coherent flow.
Outline method: Questions & Answers
Can you imagine how the conversation typically goes with a prospect? The typical questions they ask and the answers you give.
Well, use this as a starting point.
Jot down the questions you think the reader will be asking themselves as they go down the page, along with a few relevant points to build up the answer for each one.
For my own site, the first few Q&As could be:
What is this?
Messaging for devtools
Overcome sales skepticism
Improve both lead quantity and quality
How does it work?
Work through the message elements
Interview sales and support
Does it really work?
Before-and-after example
Details of reasoning and result
Your subheadings will then become the answer to the question, with the body copy and imagery providing supporting details.
Outline method: Define the workflow
Another great outlining technique is to use the product workflow as a framing device. You can show them the value you bring at each step, weaving in benefits or counter objections.
This method is ideal if your tool is the first of its type or works in an unexpected way.
I typically have an intro section introducing the overall concept, before writing out the steps and relevant details.
Here is an example workflow outline for a recent DevEx feature I helped with:
No more rebase races
- No logic conflicts or broken main branches
1) Add PR to queue
Submit and walk away
No more checking back to rebase
2) Branch is re-tested
Tests against latest main for logic conflicts
Prevents firefighting a broken main
3) Reports for debugging
Exact detail of any conflicts
Fix conflict in a matter of minutes
Again, your subheadings can turn into descriptions of the benefits as needed and bullets expanded into copy.
Turning the outline into content
Now it’s finally time to create actual content. It should be much more straightforward now that you’re only thinking about how to present it, not also what you should be presenting.
For each section, make sure you’re showing a clear link between the benefit, pain point and feature as appropriate.
This will require a combination of copy and imagery. One potential format is the subheading as a main benefit, while the feature is the image and details are a combination of more specific benefits and features.
Finding the best way to communicate the concepts does take some amount of feel and experience, but should be much easier now that you’ve set the groundwork.
I would go into detail, but this brings us into copywriting and visuals which are too big to cover in this guide.
Final thoughts
Congratulations, you should now understand how to create compelling content for developers. If you follow this approach you should always hit the key points with a smooth flow in a way that’s easy to understand.
I would recommend setting aside a few hours to go through this process. I’ve done it many times myself and it can still take me days to nail all the details, but the sales boost is worth it.
Go ahead and apply the principles to any piece of sales material. This is all just as relevant to a homepage as it is to a sales presentation.
Want help pitching your DevTool?
If you’d like help making sure you create the best possible pitch, drop me an email.
As you’ve seen, I love helping DevTools communicate why they’re awesome and how they can help. You can reach me at