I still remember the first time I walked out of a developer advocate’s talk feeling like I’d just been pitched a timeshare. The speaker was clearly brilliant. The slides were immaculate. The live demo ran without a single hiccup. But something about the whole performance felt off. It took me a while to put my finger on it: there was no friction. No edge cases. No awkward moments where the tool did something unexpected and the presenter had to debug it live. It was a flawless tour of the happy path, and when I asked a pointed question about concurrency behavior under load, the answer was a smooth deflection wrapped in a smile. That’s when I realized I wasn’t talking to an engineer who wanted to help me. I was talking to a salesperson who happened to know how to write a for-loop.
Developer advocacy has a trust problem. Not because advocates aren’t smart or well-intentioned—most of them are. The rot comes from the incentives. When your performance review hinges on sign-ups, pipeline influence, or product-qualified leads, the advocacy becomes theater. And developers, being the pattern-matching, bullshit-detecting creatures we are, can smell it from the first slide deck.
The Demo That Lies by Omission
Let me give you a concrete example. I recently watched a recorded workshop for a popular API gateway. The advocate walked through setting up rate limiting in under ten minutes. The code was crisp:
const gateway = new APIGateway({
rateLimit: {
windowMs: 60000,
max: 100
}
});
app.use(gateway.middleware());
It worked perfectly in the demo. What wasn’t shown? The fact that the default in-memory store falls apart the moment you have more than one instance. No mention of Redis. No discussion of race conditions when two nodes process the same request. No warning about the performance hit from synchronous counter increments under high concurrency. The advocate knew this—I checked their GitHub history later and found they’d filed issues about these exact problems six months prior. But the workshop was designed to convert, not to educate.
This is the core rot. When advocacy becomes a funnel, technical honesty becomes a liability. You can’t say “our rate limiting is great for single-instance deployments but you’ll need to architect around it for anything serious” because that sentence might cost a sign-up. So instead, you say nothing. You let the developer discover the footgun on their own, three weeks into a proof of concept, when they’re already invested. That’s not advocacy. That’s a trap.
The Documentation That Only Works on Happy Paths
The same pattern infects documentation. I’ve lost count of how many SDK readmes show a pristine “Getting Started” example that works for exactly one use case: the one where everything goes right. Here’s a real snippet I found in a database connector’s quickstart guide:
const db = new Database({
host: 'localhost',
port: 5432,
username: 'admin',
password: 'password'
});
const result = await db.query('SELECT * FROM users WHERE id = $1', [userId]);
console.log(result.rows);
No connection pooling. No retry logic. No mention of what happens when the query times out or the connection drops mid-transaction. The implicit message is: “Look how easy this is.” The actual message, to anyone who’s run a production system, is: “The people who wrote this have never run a production system, or they’re hoping you haven’t.”
Good advocacy would show the ugly parts. It would include a section on connection management with exponential backoff, or at least link to it. It would acknowledge that the happy path is a lie we tell ourselves to get through a demo, and then it would show you the real path. But that doesn’t convert as well. So the ugly parts get buried in a wiki page that’s three clicks deep, if they exist at all.
The Trust Equation: Competence Without Candor Equals Zero
There’s a well-known formula for trustworthiness in professional relationships: trust equals credibility plus reliability plus intimacy, divided by self-orientation. In developer relations, we can simplify it further. Trust equals demonstrated competence multiplied by perceived candor. If either factor is zero, the product is zero.
An advocate who only shows you the polished, happy-path version of their product is signaling high competence but zero candor. The result is still zero trust. Developers will smile, take the sticker, and then go back to evaluating your tool based on what they can find in Stack Overflow threads and GitHub issues—because that’s where the truth lives.
I’ve seen this play out with a CI/CD platform that spent heavily on advocacy. Their advocates were everywhere: conferences, podcasts, live streams. The demos were beautiful. But when I actually tried to migrate a monorepo with interdependent services, the build caching kept corrupting. The fix was buried in a community forum post from a frustrated user, not in any official content. The advocates knew about the issue—I later confirmed this with an engineer who worked there—but they were instructed not to bring it up unless asked directly. That’s not a technical limitation. That’s a policy choice. And it’s a choice that erodes trust.
When “Community” Becomes a Lead-Gen Channel
Another symptom: Discord servers and Slack communities that feel less like communities and more like support funnels with a thin veneer of camaraderie. You join to ask a question about a weird serialization bug, and within minutes you get a DM from a “developer success manager” asking if you’d like a personalized demo. The bug? Still open. The DM? Very friendly.
This is advocacy as a conversion surface. The community exists not to help developers solve problems, but to identify developers who are close to buying. The advocates in these spaces are often genuinely helpful people, but they’re measured on how many conversations they can move to a sales call. So the help becomes conditional. You get the real answer if you’re a qualified lead. Otherwise, you get a link to the docs you’ve already read.
I contrast this with a smaller open-source project I contribute to, where the core maintainers answer questions in the public issue tracker with brutal honesty. “Yeah, that’s a known limitation. We haven’t had time to fix it because we’re prioritizing the new parser. Here’s a workaround, but it’s ugly.” That sentence builds more trust than a hundred polished webinars. Because it’s true.
What Real Advocacy Looks Like in Code
Real advocacy doesn’t hide the trade-offs. It leads with them. Imagine if that API gateway workshop had started with this slide:
// WARNING: This demo uses in-memory rate limiting.
// It works for a single instance. For production:
// - Use the Redis backend (see docs/rate-limiting-redis.md)
// - Be aware of the race condition described in issue #2341
// - Consider using a token bucket algorithm if you need burst handling
That’s not a sales-killer. That’s a trust-builder. It tells me the advocate respects my time and intelligence enough to give me the full picture. It also tells me the product team is mature enough to document their own shortcomings. That’s a product I want to bet on, because I know what I’m getting into.
Another example: a database company whose advocate wrote a detailed migration guide that included a section titled “When You Shouldn’t Use Our Database.” It listed specific workloads where their product performed poorly—write-heavy time-series data, for instance—and suggested alternatives. That guide went viral among engineers. Not because it was flashy, but because it was honest. The company’s sign-ups increased after it was published. Trust, it turns out, is also a conversion strategy.
The Incentive Problem
Why does advocacy drift toward sales? Because the people funding advocacy teams often come from sales backgrounds. They understand pipeline, conversion rates, and MQLs. They don’t understand that a developer who trusts your advocate is worth ten who just clicked through a demo. The metrics are easier to track in the short term, so the short-term metrics win.
I’ve talked to advocates who are explicitly told not to write about competitors, not to mention limitations, and not to engage with negative feedback publicly. One was reprimanded for helping a user debug a competitor’s product in a public forum. The reasoning? “It makes us look like we’re not the best solution.” The reality? It made the advocate look like an engineer who cares about solving problems, regardless of the tool. That’s exactly the person other engineers want to talk to.
If you’re running a developer advocacy team, here’s a concrete suggestion: measure trust, not leads. Track how many times your advocates are cited in external forums as a helpful source. Track the sentiment of responses to their content. Track whether developers come back to your advocates with harder questions, because they expect a real answer. These are lagging indicators, but they’re the ones that matter.
The Code Review Test
Here’s a heuristic I use when evaluating whether an advocacy effort is genuine: would the content pass a code review from a skeptical senior engineer? If you showed the demo code to someone who has maintained the system for five years, would they nod along or start pointing out all the missing error handling? If the latter, the advocacy is failing.
Let’s apply this test to a common pattern: the “build an app in 15 minutes” video. These are popular because they’re impressive. But they’re also dishonest. No real app is built in 15 minutes. The video skips environment setup, dependency hell, the three hours of debugging a misconfigured environment variable, and the moment where you realize the library version you installed is incompatible with the example code. A code review would flag all of this. A genuine advocate would include the debugging session, or at least a blooper reel.
I’m not saying advocates should never simplify. Simplification is necessary for teaching. But there’s a difference between simplification and deception. Simplification says: “We’ll ignore authentication for now, but here’s where you’d add it.” Deception says: “Look, authentication just works!” while hiding the fact that the demo uses a hardcoded token that expires in an hour.
Rebuilding Advocacy from First Principles
If I were designing a developer advocacy program from scratch, I’d start with a single rule: advocates must be able to say “no” to anything that compromises their technical integrity. No forced product mentions. No hiding known issues. No pretending that a feature is production-ready when it’s not. If the product can’t survive that level of honesty, the problem isn’t advocacy—it’s the product.
I’d also decouple advocacy from marketing and attach it to engineering. Advocates should report to a VP of Engineering, not a CMO. Their performance reviews should include feedback from the engineers they’ve helped, not just the leads they’ve generated. And they should spend at least 20% of their time contributing to open-source projects unrelated to their company’s product, to maintain their own technical credibility and empathy for the developer experience.
Finally, I’d invest in what I call “negative documentation”: official guides that explain when not to use the product, what the known failure modes are, and how to recover when things go wrong. This is the content that sales teams fear and engineering teams love. It’s also the content that gets bookmarked, shared, and cited. Because it’s useful.
FAQ
How can I tell if a developer advocate is being genuine or just selling?
Look for the presence of limitations and failure modes in their content. A genuine advocate will proactively mention edge cases, scaling concerns, and known issues. If the content only shows the happy path and avoids any mention of trade-offs, it’s likely sales-oriented. Also, check their public activity: do they help people with problems unrelated to their product? Do they engage honestly with criticism? Those are strong signals of genuine advocacy.
Why do companies let advocacy become sales-focused?
It’s usually an incentive problem. When advocacy teams are measured on metrics like sign-ups, pipeline influence, or product-qualified leads, the behavior follows the measurement. Many organizations also place advocacy under marketing leadership, which naturally prioritizes conversion over education. The fix requires structural changes: different metrics, different reporting lines, and a culture that values long-term trust over short-term leads.
Can advocacy that admits product weaknesses still drive adoption?
Yes, and often more effectively. Developers are trained to evaluate trade-offs. When an advocate honestly presents a product’s strengths and weaknesses, it helps developers make informed decisions and builds credibility. Many successful open-source projects and developer-focused companies have grown precisely because their advocates were trusted sources of truth, not just cheerleaders. Trust is a durable competitive advantage.
What should I do if I’m a developer advocate feeling pressure to hide limitations?
First, document the specific instances where you feel your technical integrity is being compromised. Then, have a direct conversation with your manager about the long-term cost of eroding developer trust. Propose alternative approaches, such as creating honest content that addresses limitations while still highlighting strengths. If the organization refuses to allow candor, consider whether the role aligns with your professional values. The best advocates are often those who are willing to walk away from a position that demands dishonesty.