How to Write Persuasive Technical Content
I’ve gotten to be a big fan of David Perell’s writing. He writes long-form, persuasive content where he dives really deep into a topic and then explains its relevance in philosophy, business, or both.
Examples include:
While not technical, these pieces are interesting, inspiring, and (as I’ll focus on today) persuasive. They each leave you with an impression that something is wrong with the world or its traditional ways of thinking and give you a roadmap to break out of it. While you may not agree with all of Perell’s conclusions, most of his arguments are well thought out and clearly presented.
Persuading software engineers or engineering leaders is essentially no different from persuading writers and businesspeople, but writing persuasive technical content is really hard. Persuasive writing is among the most difficult types of writing to do, and writing technical content requires a very specific background and level of experience.
But, persuasive technical writing is incredibly valuable because it’s so rare. CTOs and technical visionaries who do it well often make the front page of Hacker News, and will find it easier to recruit, sell, and inspire others toward their goals.
In this piece, I’ll introduce some of the things that make persuasive technical content so hard. I’ll share examples of writers I’ve seen who do it well, and I’ll offer a few tips as an observer and writer. While you can’t get really good at writing without practice, I hope having some direction will help guide you towards becoming a better persuasive writer.
What is Persuasive Technical Content?
Before I jump into the how, let’s talk about what persuasive writing is and why people do it. Persuasive technical writing is a form of technical thought leadership where the author is attempting to persuade their reader to agree with them on some topic. Typically, the author wants the audience to see the same problem or solution they do.
For example, in 2018, I wrote a blog post titled, “The Bulk of Software Engineering is Just Plumbing,” in which I made the case that most of the work software engineers do is simply connecting pieces of software that other people built for them.
“Just as a good small business owner should hire a humble plumber who knows the standard tools, and pay them market rate, a good engineering manager should hire humble team players who use industry-standard tools to build reliable software, and pay them market rate.”
I wanted engineers and hiring managers to adopt a bit more humility in the profession, and based on the reception I got on Reddit and Hacker News, many readers agreed.
While I would never claim to be a master of persuasive technical writing, I’ve tried (and failed) enough times to tell what works. In 2020, I wrote almost 100 essays and blog posts, many of which were persuasive technical pieces. So, let’s take a look at some of the attributes that good persuasive writing exhibits and how you can use each in your practice.
In Order to Persuade, You Must be Understood
“Good writing is fundamentally good thinking that follows a logical path and is easy for someone to follow.” - Jeff Bradford, President & CEO of the Bradford Group
As with any effective form of writing, your work must be well-written and organized. Some forms of writing are more forgiving (for example, tutorials), but with persuasive writing, the bar is especially high. Poor grammar and hard-to-follow lines of reasoning will turn readers off quickly.
Persuasive Technical Writing Should be Authoritative
“A statement is persuasive and credible either because it is directly self-evident or because it appears to be proved from other statements that are so.” - Aristotle
If you’re trying to reach a knowledgeable audience with a persuasive argument, you need to be perceived as knowledgeable about the topic. This is called “building authority,” and there are many ways to add it to your writing:
- Research
- Quotes
- Personal Experience
One of our Draft.dev writers, Keanan Koppenhaver, does a good job of this in his persuasive writing. This piece he did for Fabric.inc compares Shopify and Salesforce Commerce Cloud by going through specific features and limitations of each platform.
He draws on his personal experience in software as well as publicly available documentation and forum posts to bolster his arguments. Being a CTO and consultant helps boost his credibility as well because a piece like this written by a Fabric marketing executive wouldn’t be nearly as convincing.
Persuasion Should be Subtle
“Written arguments often fail when they employ ranting rather than reasoning.” - Tara Horkoff, Writing for Success
The best persuasive writing doesn’t beat you over the head with the author’s conclusion. Instead, it guides readers toward the desired conclusion by:
- Establishing authority
- Asking questions
- Being helpful
- Showing both sides of the argument
Some persuasive writing doesn’t even tell readers what to think, but instead, just leaves readers with an open question. I recently ran across a Twitter thread by Sam Altman predicting the end of the college education system in the US:
I think US college education is nearer to collapsing than it appears.
— Sam Altman (@sama) March 20, 2022
While he presents some partial answers, it’s more focused on the problem and implied question (“what comes next?”) than the solution.
Persuasion is Often Personal
“I have a theory that the best ads come from personal experience. Some of the good ones I have done have really come out of the real experience of my life, and somehow this has come over as true and valid and persuasive.” - David Ogilvy
Finally, some of the best persuasive writing is borne from personal experience.
For example, a couple of years ago, I noticed that asking experts for direct advice was almost never helpful. Instead, I started asking them how they solved a particular problem or managed a certain conflict.
This led to me researching the issue and writing a persuasive piece on “The Danger in Listening to Experts.”
I started with a topic that I had personal experience with but layered in data, quotes, and supporting arguments from others who had spent even more time with the topic. While the piece never got a ton of attention online, I refer people to it when they ask me for advice, so I’ve found it useful in other ways.
Conclusion
While we do a little bit of “light” persuasive writing at Draft.dev, I encourage most companies to do this form of writing in-house. If you’re a startup, your founders are probably the best people to make a compelling case for your world-view, and if you’re in a large enterprise, you probably want your PR or executive team collaborating on these pieces.
On the other hand, if you’re a software developer or engineering leader who just wants to write persuasive technical pieces, I’d encourage you to do so on your own blog. While some companies may pay you for these, you’ll get a much more authentic reception when you do it for your own gratification.
By Karl Hughes
Karl is a former startup CTO and the founder of Draft.dev. He writes about technical blogging and content management.
Build a Blog that Software Developers Will Read
The Technical Content Manager’s Playbook is a collection of resources you can use to manage a high-quality, technical blog:
- A template for creating content briefs
- An Airtable publishing calendar
- A technical blogging style guide