Spilling the tea on writing for developers as a marketer

Originally published here.

If you’re reading this, you probably consider yourself a writer: obsessive notebook scribbler, perhaps an English-degree holder, forever a novelist-in-the-making. (We can relate.)

As journalism jobs have shuttered and academic positions grow ever more precarious, content writing has emerged as a kind of salvation: A job where you can get paid to write all day and make enough money to afford name-brand Nutella? Sign me up.

There’s only one, teensy, tiny catch. A lot of the content writing work that’s in-demand is technical in nature. And you’re not a technical person. So what do you do?

Before you start panic-Googling coding bootcamps, we have an easier solution: Fake your technical competency. Strategically.

In this article, we’ll share how we—two artsy English majors—write for developers. And we’re here to spill all our best-held secrets. Are you ready? (It’s not nearly as scary as you think, we promise!)

Why should you trust us?

We’re Mariya and Carina, two content writers and strategists. We’ve built our careers by writing about topics we know absolutely nothing about (well, at least not at first).

Mariya founded a content agency specializing in content creation and strategy for B2B tech. Carina was the first full-time employee (and now managing editor) at a content studio that does strategy, writing, and design—primarily for B2B tech, as well.

Our educational backgrounds couldn't get much further from that of your typical developer. Mariya has a BA in Literature and Creative Writing from NYU and Carina has an MA in 18th century British literature from Oxford.

While our degrees might make you think that we'd run and cower behind the nearest bookshelf whenever someone says "Javascript," we actually have a trick up our sleeve: Both of us worked as peer tutors in our undergraduate writing centers.

For the uninitiated, peer tutoring is a consultation service offered by some universities. Students can bring in essays or other coursework and get feedback on their writing—not just on the mechanics of grammar or spelling, but also on their overall argumentation, structure, and flow.

That meant tackling a deluge of papers on topics that we knew nothing about. And we didn’t have to just read and understand them, we also needed to give constructive criticism on how to help people improve their work (all within the time limit of a single appointment slot!).

Our training turned out to be an incredibly useful skill in the marketing world. And, returning to the topic of this blog post, it’s given us the confidence to parse difficult topics and make sense of technical materials.

And, as you’ll soon discover, when it comes to writing for developers, confidence is half the battle.

Build your confidence: Why technical content feels so intimidating and what you can do about it

1. You think you need “special skills”

You might think that you’re unqualified to write about a topic because you don’t have the right background. Some marketers will even argue that it’s easier to have subject matter experts write their own content—we disagree.

It takes years to develop a taste for good writing and master effective communication. In our experience, it’s far easier (and faster) to teach someone with existing writing skills about a new topic than to teach a non-writer the skill of writing well. Plus, many technical people don't want to write their own content but still need to communicate their ideas to the world. (You’re honestly doing them a favor!)

Remember: you’re a writer. That means you’re also a “re-writer”. So if you think you’re unqualified to write on technical topics, start by rewriting the internal belief that you’re unqualified to write about them. As a writer, you’re actually perfectly qualified—and technical people will be grateful for your help.

2. You’re number-phobic

Math anxiety is a very real thing. Many of us had bad experiences in math or science class, and we still have residual traumas from those memories. It’s easy to label yourself as “not good at math” or “not smart enough” and feel intimidated by these technical topics.

The problem is, these internalized negative beliefs actually hijack our brains. When math-anxious people anticipate solving a math problem, the parts of their brain responsible for detecting threats and processing pain begin to activate. Instead of focusing on the problem at hand, you get stuck grappling with intrusive thoughts about why you’re not getting it yet.

Math anxiety, like other forms of anxiety, can be a complicated knot to untangle. But there are things that can help. Try to relax your expectations of yourself—you don’t have to be perfect. In fact, we’d argue that getting things wrong is a core part of the process of doing good technical work (or writing about it).

If you can give yourself some breathing space, it will be much easier to focus on the problem in front of you.

3. You don’t know how to “speak developer”

You might have heard that engineers hate “marketing speak.” It’s possible you’ve even heard developers at a current or previous company disparage marketing as “the arts and crafts department” while they do “real work” (this is not very nice, by the way).

While it’s true developers have different content preferences, they’re people too—they laugh at memes, get frustrated over bugs, and spend way too much time Googling answers to questions they don’t know the answers to.

Speaking to developers is just a question of learning how to address a new audience—which as a writer, is something you’re already great at. You just have to understand their mindset. That’s what we’ll get into in the next part of the article.

Understanding the developer mindset

To write effectively for developers, you need to be able to get into their heads and empathize with their experiences.

How do you do that? You go to the source: One of the best ways to understand developers is to talk to them regularly. And if the idea of striking up conversations with developers triggers your social anxiety, don’t worry—you can learn a lot from just immersing yourself in the online communities where they hang out, like Reddit, Stack Overflow, and GitHub.

That said, you can learn a lot by asking developers for coffee chats. Treat them as a kind of “informational interviewing”—getting informal advice and talking to people about their experiences.

And you don’t need to feel intimidated. In fact, you might be pleasantly surprised how willing they are to share about their work. (As it happens, most people are happy to talk your ear off about the things they’re passionate about.) So go, and see if you have any acquaintances in your network or connections on LinkedIn who would be willing to let you pick their brain.

As you spend more time talking with developers, you might find that what they want out of writing can be a bit counterintuitive.

For instance, it’s a common piece of writing advice to define acronyms or complicated terms when you first use them—this is a way to be friendly to your audience (after all, you want to make sure they understand what you’re talking about). Normally, this is good advice, but when writing for developers, this innocent practice can backfire.

Developers want to know that the person writing the article knows what they’re talking about—and for them, defining basic terminology can make it seem like the writer isn’t particularly advanced (or the article is designed for a beginner in the field).

The power of technical writing: Communicating complex ideas in simple terms

Here, we’ll explore the different types of technical writing and the formats used to present technical information. Then we’ll also dive into the importance of technical writing for developers and companies and discuss what you can do apart from technical writing.

Developer Marketing AllianceReet Batra

Dropping key terminology without defining it can actually make developers trust you more—it’s a way to “flash your badge” as a credible expert who knows what they’re talking about.

How to read technical texts

Reading a dense technical text is not all that different from reading a dense work of philosophy or literary criticism. And chances are, if you hold a humanities degree, you’ve done this before. If you’ve heard of the term “close reading,” then that’s exactly how you should approach reading technical texts too.

Go back to basics when reading a technical text:

• Establish your purpose before you begin to read: What are you trying to learn?
• Read the abstract and skim the introduction, conclusion, headings, as well as any tables, or diagrams to help orient yourself before reading the whole thing through
• Write down any terms you don’t understand and look up their definitions
• Note any questions that pop up as you read
• Take notes on key themes as you go.

The key here is to trust yourself and to use your confusion as a learning tool instead of an obstacle. Whatever you’re confused about might spark a new idea later in the process, or you could even incorporate your questions into your own piece.

Remember, you aren’t the only one confused by all of this technical detail. Even experienced developers might have questions and will be grateful that someone has finally answered them.

When reading developer texts in particular, you can use our 3-part framework on what to look for:

• Emotion: can you see how the author of this text feels about the subject?
• Change: can you find any indication of the topic or the product discussed changing over time?
• Vocabulary: can you discover any technical terms and jargon that might be important?

Let’s dig a little deeper into each one.

Find the emotional core

If you’re reading technical texts for the purposes of writing about these topics later, you should locate the emotional core behind all that scary jargon.

As you’ve probably seen in your previous work, good writing appeals to feelings. Otherwise, why should anybody care about your content? If all you’re doing is reciting the facts, then your readers would be better off going to Wikipedia or reading a list of API endpoints on their own.

Think of your role as a tour guide. In a way, you are inviting your readers to walk along with you, and experience the topic that you’re writing about. So, like any good tour guide, you should make that journey fun and memorable. And what makes a 1-hour deep-dive into a medieval castle fun? The battles fought and the heroes who won them.

The same principle works for technical writing: you’re inviting developers to take a tour of a particular concept or product. Show them around by telling them a story. To craft that story, imagine every text you read as a clue to discovering who lived in your metaphorical castle, what they believed, and how they felt about it.

Mariya likes to divide up these emotional clues into two parts:

• Rants: signs of strong negative emotions. These could include frustration, annoyance, fear, anxiety, and anger.
• Raves: signs of strong positive emotions. These could include excitement, love, anticipation, curiosity, and joy.

If people are expressing strong emotions in what they’re talking about, then your readers might feel the same emotions when you talk about that topic later on. Use that emotional resonance in your own work!

Look for signs of change

Software changes… all the time. If you are reading any text about tech, we guarantee that the context around it has involved lots of major changes and developments.

One hack to quickly get up to speed on a certain topic is to look for signals of recent changes. The obvious places to find them are, well, changelogs and release notes. Both types of documents are created specifically to communicate what has been added to or removed from a piece of software.

Glance through the past few months of changelogs and take notes on what features seem to be getting updated most often and what bugs are getting prioritized.

In other technical texts, notice words and phrases signaling change. Those could include:

• “Used to”
• “Before”
• “Instead”
• “New”
• “Old”
• “When we changed to”
• “After the shift”
• “When we adopted”
• “Once we implemented”
• “In contrast to [old way]”
• “Similar to [old way]”
• “Because of [problem], we tried”
• Etc.

You could dig deeper into these changes, trying to understand the underlying reasons for them and the pain points that those changes were trying to solve.

Record key vocabulary

Does reading technical texts feel like you’re navigating a different language?

You’re not alone—it often feels the same for us too. So, embrace it: approach your reading just as you would an actual foreign language. Identify unfamiliar vocabulary by highlighting the terms in your reading (if you are able to) or copying those words into a separate document.

Mariya also suggests trying to guess the meaning of those terms and writing your guesses down before you look them up. It’s a small pedagogy trick that will help you remember the actual meaning of that term better later on.

If you notice any jokes that are dependent on jargon and technical terminology, then those are great to look up as well. Try to dissect the jokes or memes that you see developers sharing, and you will be one step closer to speaking their language!

3 steps to writing for developers

Now that you’ve figured out how to read technical texts and do some initial research, it’s time to dive into the actual writing process.

But, since it’s dangerous to go alone, you should take this framework with you:

1. Begin formulating questions
2. Talk to an expert
3. Tell stories.

Step 1. Begin formulating questions

Before you can understand your topic enough to write about it, you need to figure out what you don’t know.

Having questions is nothing to be ashamed of! Don’t worry about looking silly—that’s why you’re going through this entire process. A bit of preparation will help you come up with educated and specific questions that will impress your subject matter experts more than you expect.

Start by getting into the heads of your audience. Dive into their world by reading the same content as they do. Read through developer blogs, discussions, and newsletters. Mariya tends to use SparkToro to both find and analyze that content, but you can do it manually or with your preferred research software.

If you’re writing about a specific product or tool, make sure to look through its developer documentation, changelog, and release notes. Pay attention to diagrams and code snippets and try to guess what they are talking about (even if you don’t understand all or even most of it).

As you read, (and this is important!) write down everything that you’re confused about and what seems important. If anything jumps out at you, trust your instincts.

Even if you can’t articulate why a certain sentence or paragraph stood out to you, you’re probably not the only one feeling that way. Similar to our process for reading technical texts, remember to write down any specific terms and vocabulary that you see over and over.

Once you’re done, turn your notes into a list of questions and prioritize any themes that you see popping up again and again across your notes.

Step 2. Talk to an expert

Now that you know what you don’t know, it’s time to get some help.

Ideally, you should try to get on a live call with a subject matter expert. If you have access to technical professionals within the company you’re writing for, try to interview one of their head engineers or their CTO. Depending on the size of that company, you might also want to talk to their regular developers, who are typically more on the ground and familiar with the minute details of their code.

Try to schedule your interview to last between 30 minutes to an hour. For some projects, you might need to interview multiple experts or book a single expert for closer to 3 or 4 hours. But in the beginning, start small. You can always ask follow up questions and schedule more calls later if you need them.

During the call, ask the questions that you wrote down in Step 1. Don’t worry about looking silly, and try to dig in until you properly understand the answers. You should also pay close attention to emotion within your interview subject’s voice and dig into the reasoning behind their technical explanations.

Step 3. Tell stories

What brings technical stories to life is when you share the examples and stories from experts in that field—so it’s important to delve into the emotional core behind those technical details.

It sounds counterintuitive, but sometimes you don’t even have to fully understand what your interviewee is saying to get value out of the call. Something Carina has learned is that if an interviewee seems particularly passionate about a given topic, it’s best to let them talk, even if you haven’t quite grasped it yet.

You can always turn to Google or YouTube to give you a better understanding of a technical topic, but you only have this one opportunity to get great quotes and anecdotes from someone who’s lived through it.

Try asking some of the following questions to help unlock emotions and stories within your interviewee’s experience:

• What do you love about what you do?
• Tell me about your best day at your job
• What do people not understand about your role?
• What keeps you awake in the middle of the night?
• What’s top of mind for you right now and why?
• What do you wish people knew about…?
• What are common misconceptions about…?
• What’s one of the most frustrating experiences you’ve had with…?
• What are you most proud of accomplishing in your role?
• Tell me about a time when…

As you’re probably already aware, a crucial component of good storytelling is tension. As you’re interviewing, consider: What are the stakes? So what?

Take this example: A team is struggling with bringing their NetSuite customizations over from a development environment to production.

Why should we care? Well, if they don’t solve it, the project will get delayed and they won’t be able to use the enterprise resource planning (ERP) tool they’ve spent months painstakingly setting up. They’ll let down all the other teams that are depending on them. The CTO will be put in the embarrassing position of having to explain the delay to her board.

Sounds much more interesting now, right?

Behind every technical problem is a human story—and identifying the stakes allows you to spin that tale in a compelling way.

Some walkthrough examples

Now that we’ve walked you through our process, let’s look at some examples of how we’d approach reading through real-life technical texts.

For the sake of fairness, we have not seen these texts before working on this blog post, and did not use them in any of our client projects.

Mariya’s example

We'll each take turns showing you our approach. I (Mariya), will start.

I wanted to find a recent and relatively popular example from the developer community, so I went on Dev.to (which you should definitely frequent if you’re working with developer marketing!) and filtered for “Top” posts this month.

This piece jumped out at me as it has a fair amount of engagement, is on a topic I know nothing about, and is supposed to be a 5 minute read:

I won’t bore you with the entire article, so let’s look just at the first couple of sections. I’ll include a screenshot of whatever section I’m reading before showing you my notes. Feel free to try working through the example yourself as you follow along!

Reading the introduction, I’m immediately noticing the following vocabulary:

• Refactoring: it’s in the title of the piece, so it’s probably important. Convenient that the author gives us a definition right from the start!
• Readability, Maintainability, Scalability: I vaguely know what these words mean in relation to code, but I am hazy on the exact definitions
• Performance and Developer Productivity: if I am trying to write an SEO optimized piece, these already pop out as potential keywords.

This introduction is also good for noticing signs of emotion, so let’s start filling out a little Rants and Raves table:

There aren’t many signs of change here, but we have a sort of before and after set-up in terms of writing code with and without refactoring.

Moving on to the next section:

My brain is already starting to melt down, which is a good sign because I’m learning. So I will dig into my confusion and record some questions:

• How can techniques for refactoring be different to integrating refactoring? Aren’t those the same thing?
• Why do I need to integrate certain techniques into my process before looking at other ones?
• Is there a hierarchy of refactoring techniques where some are more advanced than others?
• When in the coding process should I refactor my code?
• How can a team work collaboratively on refactoring? What do teams usually get wrong?

For the sake of brevity, let’s look at only one more section before reading the comments:

I see code and my eyes immediately glaze over. But we are pushing past our fears here, so let’s read the explanation and look at the actual code snippet.

We’ve got some new vocabulary to note down:

• Extract Method
• Function
• Identification
• “For” Loop.

Now, I want to figure out why the code snippets look the way they do. For this, I will look for clues within the author’s explanation.

They are obviously extracting some part of the code and moving it somewhere else. The reason for that is, apparently, to make the code more manageable.

Okay, so if I stare at the before and after code snippets side by side, I see that the “before” snippet only has one function, “calculateInvoiceTotal”. The “after” snippet has kept that function but also added another one called “calculateItemTotal”.

Now I am trying to find what exactly they took out and added into that second function. Going through the “calculateInvoiceTotal” function line by line in both examples, I see what they’ve extracted: the “if” statement for calculating total price for an item.

Both of these code snippets make sense. Before refactoring, we had a function with a nested “if” statement, that can easily be turned into its own separate function. So the “Extract Method” means taking out these separate sub-functions that are hiding within larger ones and separating them out into their own functions.

To conclude our example, I want to show you some of the comments so we can finish our Rants and Raves table from above:

And here’s a final version of our table:

Of course, we could analyze this piece even deeper, but I would probably end my research at that.

Carina’s example

Carina here—now it’s my turn. For this example, I went to the trending articles section on GitHub’s blog. At random, I picked #5, “We updated our RSA SSH host key.”

Like Mariya, I’ll post snippets of each section before sharing my notes, so you can follow along. First, I did a quick scan of the title, subheads, and images to help me get the lay of the land.

Here’s what I noticed:

• The post is categorized under “security”
• They use the language “out of an abundance of caution”—so there must be some potential risk at play
• The timing is very precise—it makes me think that time this change occurred is significant
• Scanning the subheadings “What happened and what actions have we taken?” and “What can you do?” further confirms for me that they’re talking about about a security threat
• There are also some code snippets provided, which tells there may be things that users need to look out for or action they need to take.

Now, let’s read the whole thing through, starting with the introduction and going section by section.

Already, I’m awash in vocabulary that’s unfamiliar to me, which I’ll start jotting down.

• RSA SSH host key
• SSH
• RSA
• ECDSA
• Ed25519.

This post is written in the calm, authoritative voice of GitHub (“we”) rather than any individual person, so there may be less to glean in terms of rants or raves. Still, there are some words connoting fear, which we may want to slot under the “rants” category:

• “Abundance of caution”
• “Protect our users from any chance of an adversary impersonating GitHub or eavesdropping on their Git operations”.

What seems most significant here, however, is a change that took place.

I think I’ve grasped the basics, but I still have more questions than answers, so I’ll jot down the things I’m still wondering about, such as:

• Why was this change necessary? Did something happen?
• How does the RSA SSH host key work?
• Why weren’t ECDSA and Ed25519 users affected?
• What are the implications for users now?

At this point, I may want to look up some of the tricky vocab to help me understand it better. After some quick Googling, I discovered that SSH stands for “secure shell” and is a type of encrypted communication protocol (kind of like http, which is used to transfer web pages so we can read them). RSA, ECDSA, and Ed25519 are all key-generation algorithms you can use with SSH.

Okay, so I’m still not a cryptography expert, but I kind of get what’s going on: GitHub’s RSA SSH key was leaked, causing a vulnerability which they’ve now taken action to correct. (To answer one of my above questions, this is RSA-specific, so other key types weren’t affected).

I still don’t know why it happened or what these changes mean. I’ll keep reading and see what I can find out.

I’m starting to piece together the story:

1. GitHub’s RSA SSH private key was briefly exposed, leaving users vulnerable to a potential attack (we learned in the intro that this attack could be a bad actor impersonating GitHub or eavesdropping on users’ private conversation)
2. There’s no evidence that the exposed key was abused, they just wanted to be cautious
3. GitHub swiftly replaced the key.

Okay, great. So what does this mean for GitHub users? Let’s keep reading.

This seems straightforward enough. But what about for users who were affected? Here, I see some snippets telling me what to look for and what to do next.

So we’ve removed the old key. What next?

There’s some additional information at the end of the article around troubleshooting, but I think I’ve now gotten the gist. Let me summarize everything I’ve learned into this table:

Writing for developers troubleshooting

How can I find reputable experts?

Networking can feel weird and scary, but it doesn’t have to be! If you’re genuinely curious and interested, that sincerity will come across to the other party.

Begin with who you know: is there a coworker, friend, or family member who has technical expertise you could talk to? Could they refer you to anyone else with relevant knowledge or experience?

If you’re starting completely from scratch, see if there are any online groups or communities you could join. Consider putting a call-out on LinkedIn saying that you’re looking for experts in a particular topic to speak with or try cold-messaging folks with relevant job titles.

Also remember that you’re not just asking for a favor—you have something to offer too. It’s beneficial for technical experts to be featured and quoted in your work. They might not want to write on a given topic themselves, but being quoted as an expert in their field can help elevate their own personal brand.

Just remember to give your experts the opportunity to review and approve their quotes for accuracy before going live, so they can feel reassured that anything going out with their name on it comes out the way they want.

Some other ways to find experts, depending on what you’re writing about could be:

• Help a B2B Writer: a service run by Superpath, a content marketing community. You can submit a writer request and it will be sent out to their database of experts working within that sphere.
• Reddit: you can always pose your question within one of the Reddit communities that are meant for getting help from developers. Make sure to look at and follow all community rules if you’re posting! Some useful subReddits include r/AskProgramming, r/CSCareerQuestions, r/ITCareerQuestions, r/AskNetsec.
• Mastodon: a decentralized alternative to Twitter, Mastodon’s got a very active community of developers, coding enthusiasts, tech professionals, and all kinds of geeky nerdy users. If you make an account on a larger instance (like mastodon.social, mstdn.social, mastodon.world, mas.to, mastodon.online, or masto.ai) and tag your question with #developer, #dev, #tech, and/or hashtags relevant to your specific topic – someone will probably be happy to help you out!

What if I can’t talk to an expert?

Sometimes you might struggle to find an expert to talk to or the timeline will be too tight to allow you to do an interview. That’s okay—there’s still a lot you can do to get up to speed on a given topic.

There’s a wealth of information available to you online. Start by going to Google and YouTube to wrap your head around the basics. Once you know more, you’ll have more specific questions and search terms you can use to uncover more in-depth articles, academic papers, forums, technical documentation, and so on. Don’t forget to use the reading framework we shared above to help you!

Even if you can’t interview someone, see if there’s an expert at the company you’re writing for who can quickly fact-check your work. (It’s often much easier to hand someone a document and ask “is this right?” rather than getting them to explain it to you from scratch).

What do I do if I get stuck?

Don’t despair—developers get stuck too! In fact, they get stuck a lot.

Coding is 1% coding
by u/SuccMyStrangerThings in ProgrammerHumor

So what do you do if you’re not getting it? Turn to the resources you have: Google, YouTube, StackOverflow, GitHub. If you still can’t find anything, try posting your question on Reddit or Mastodon.

And if you’re still staring at a blank screen feeling like your brain has turned to mush, try taking a break. Go for a walk, make yourself a snack, or take a pause from the piece you’re writing until the next day. You’ll be surprised about how much easier things feel after you’ve had a rest.

Final thoughts: don’t be scared of technical content

Technical content is only scary because it’s unfamiliar—but there’s a lot you can do to demystify it. Remember that you already have the most important skill: Exceptional writing chops.

It’s easy to dismiss your existing skills because they already come so naturally to you, but remember that writing is hard for a lot of people. Many developers don’t want to do it and by stepping in, you’re offering an immensely valuable service.

From dissecting complicated technical texts to how to “speak developer,” you are capable of learning anything you put your mind to. What helps is a spirit of curiosity and a growth mindset. You’re going to get things wrong and that’s okay. It doesn’t mean you’re not smart, it just means you’re learning. The more you interact with and write for developers, the easier it’ll get.

And if the tables were turned and you asked a developer to do a literary analysis of a poem, they’d probably start to sweat a bit too.

Join our Slack community to pick the brains of other marketers and developers, as well as get opinions on your technical writing, network, stay on top of the latest job ads, etc.

Join the community | Developer Marketing Alliance

The Developer Marketing Community Slack community is the perfect place to connect with like-minded marketers across the globe. You’ll be able to learn and grow alongside your peers, ask questions, find job opportunities, see the latest content, and much more.

Developer Marketing AllianceDeveloper Marketing Alliance