Writing Developer Content That Delivers
Striking the right balance in content designed to encourage users to try your code, product, or solution isn’t easy. How many times have you chanced upon a web page, blog post, or tutorial, read through all the cool features it supports, but been none the wiser as to why it’s useful to you?
Technologists tend to focus on the details that they care about, which is understandable. But creators and developers are not the same as end users, even if that end user is another creator or developer. They are interested in why something is useful to them and what problem it solves, not just a list of features and innovations.
Sometimes this misdirection is intentional. Clever copy is often used as a sales tool to prompt the reader to call a pushy salesperson.
This blog isn’t a treatise on copywriting. Instead, this post is for the developer advocate who’s trying to explain what they are working on to other developers and technical users.
This post should serve as ammunition for anyone in developer content marketing (35% of DevRel teams sit in marketing according to Hoopy’s State of Developer Relations 2019) who is trying to encourage their technical colleagues to write clearly, concisely, and with purpose.
It’s OK to Start With a High-Level Overview
I am a big believer that it’s possible to reduce most things, no matter how technical you think they are, to a simplified summary. You lose detail, that’s expected, but this is for a brief 30-second introduction. If you hook someone with that, then they can dig in to get more detail.
Writing short and concise descriptions, especially if you have had your head in code for months, is difficult, and this may not be a task you can handle. That’s fine. Different people are good at different things, and maybe you need to call in someone from content marketing to assist you. I know tech-focused folk tend to shy away from that sort of idea, but we’re talking about an introductory sentence, you’re not selling your soul quite yet.
If you want to try this yourself, great! Here are some ideas to help you.
Think about what someone can solve by using your solution, service, or project. There’s a likelihood that you created it in the first place to scratch an itch you had. Think back to that, what problem(s) were you having at the time and were looking to solve?
Explain why what you are doing is better. Your work isn’t the only solution to this problem. You need to explain why someone should pick your solution instead of an alternative.
“It’s better” is not an answer, even though it often is in technical circles. Why is it better for the person using it? It’s unlikely that many end users care how well architected your project is, or that it uses the latest frameworks or techniques if that doesn’t benefit them in some way. There are visitors interested in learning from your code, and maybe they care about how awesome your code is, but end users want to know why that’s important. Does your solution deliver results faster? Is it more stable, more secure, or offer more configuration options? Those are the kinds of details that most end users care about, and each time you address one, again ask, “Why does a user care about this?”
If you find any of these questions hard to answer, maybe it’s time to question if your project is useful to anyone. GitHub is a graveyard of abandoned projects, often because they were a solution looking for a problem that no one had. A developer created something because it was cool, not because anyone needed it.
Sometimes people find it hard to explain something they have created because they are slightly skeptical about its value. It’s all too easy to get drawn into personal academic indulgence and be so absorbed by it. You lose focus on the justification for starting in the first place.
Three Tips for Getting Your Point Across
Speak clearly
Once you have refined what you want to say, the next step is to think about how to say it. Copywriters sometimes select intentionally complex or vague words for a reason, but in developer content marketing, you want to craft clear, understandable text.
Keep it simple
Don’t use words that add no value. Words for humor or character are fine (but come with complexity), but words that muddy the explanation (and thus the readers understanding) are a distraction. In English, there are words that add nothing but syntactical noise. They may be useful in fiction or creative writing, but for explanatory text, they are not useful.
Make your content globally appealing
Then there are words that people use to show off how clever they are, which is comparable to creating overly complicated code for no particular reason but to show off. Remember that often when we write in English for technical copy, when we are writing for international audiences, who are reading in their second or third language, adding complexity for your indulgence is selfish and doesn’t help anyone. If a simpler word does the job, use it. Let your code and ideas speak for how smart you are, not your knowledge of obscure English words.
Let Your Confidence Show
My final writing advice involves something subtle that I spend a lot of my time changing when I edit: You need to write with confidence. Confident writing helps people believe that what you say is true and accurate,[and doesn’t leave them unsure if they should believe what you say.
The best explanation is from Stephen King’s “On Writing: A Memoir of the Craft.” He aimed the advice at fiction writers, but I think we can all learn from it, even though he criticizes technical writers.
“The passive voice is safe… I think unsure writers also feel the passive voice somehow lends their work authority, perhaps even a quality of majesty. If you find instruction manuals and lawyers’ torts majestic, I guess it does.”
Changing from Passive to Active Voice
The first step is to make it clear who the actor and subject are in each sentence. There are often situations where this isn’t possible or relevant but try it as much as possible. Here’s an example.
Passive voice:
Functions can be used to return a value.
Are you sure about that, can they or not?
Active voice:
You can use functions to return a value.
Ahh, so I can use them!
It’s a small change, and might not even be that noticeable in isolation, but throughout an entire article, it makes a difference. Active voice clarifies details and gives the reader more confidence in what you’re saying.
Answering the Question, “Why Should I Bother”?
If you want someone to use your solution or contribute to your coding project, they need to understand why they should bother. Do not underestimate the value of a clear explanation. If someone understands what you are doing and why they are more likely to take an active interest. This article scratched the surface of advice on how to do this, and I appreciate that every project is different. I’m happy to hear from you on twitter @ChrisChinch. Feel free to send me a DM to ask for any advice.