Writing for developers
When I was a much younger human, I dreamed of being a professional fantasy and science fiction author. I spent hours – whole days – in my bedroom writing and dreaming. Writing was my safe space and my coping mechanism.
I am not a professional fiction author. As I get older, that dream recedes further into the horizon of adult disappointments. It’s not all lost though. I do get to write professionally, and while it is not quite in the form my little girl self had hoped for, it is also beyond her wildest dreams. She never thought we could work in tech.
In my current role, I get to focus on content for developers. It is a challenge I enjoy because I get to create content for myself. I know my target audience intimately because the target audience is … me.
If you’re in DevRel, it is likely writing is part of your job. Here are some insights, resources, and perspectives I think can help.
Content, technical writing, marketing, and documentation
What is content?
The term “content” – and, by logical extension, “content creator” – is so overused that it’s become self-conscious. Everyone is making content. What you are reading right now is content. There is both too much content and never enough content and is any of it even any good?
To answer that, we need to define “content.” Content is information provided by a website. Content includes blog posts, videos, podcasts, webinars, infographics, and white papers. (Not an exhaustive list.)
My role at work defines this even further. As developer content marking manager, I am responsible for the content created for and by developers with the additional feature of a call to action. Ultimately, I want the developer consuming the content to feel inspired to do something.
The intersection of content and technical writing
As an audience, developers are allergic to bullshit and I empathize with that. If I want a developer to do something, I know I have to present a compelling and logical reason for it, and my reason must be technically sound. Therefore, the argument can be made that all written developer content should be technical writing.
Technical writing focuses on communicating technical concepts and information accurately, effectively, and – in the best case scenarios – compellingly. It’s a specialized skill. Based on this review, Technical Writing for Software Developers by Chris Chinchilla seems like a good resource for getting started. I’ve added it to my reading list.
While I was exploring the rest of Fabrizio Ferri-Benedetti’s website, I stumbled upon this high fantasy map of technical writing:
Documentation is marketing
Documentation is a written description of a product or service that helps the end user “understand its different characteristics, features, and attributes.” Documentation is a form of technical writing.
And if the documentation is available online as part of a self-serve product or service, then it is also content and therefore, documentation can be marketing. Which means you really should verify that the code snippets in your READMEs actually work and make sure to communicate changes in your APIs.
Developing a content strategy
What is your call to action? Who is your target audience?
Precision is paramount to good technical writing – and that includes being precise about your call to action. Your call to action might be to install a framework. Now, how you convince someone to do that can vary, so you have to be precise about your target audience as well. When your target audience is developers, it is important to be precise about what kind of developer.
Jakub Czakon hits the nail on the head with this:
What is your target audience looking for?
So you have your call to action and your target audience, now what do you create content about? In order to figure that out, it is helpful to understand the problem your call to action is going to solve for your target audience.
The most recent Draft.dev webinar offered some useful advice for developing an SEO strategy. The most interesting takeaway for me was to find out what questions your target audience is asking and create content that helps answer those questions. This is where it is important to be precise about the personas you are trying to appeal to – knowing your personas thoroughly will lead you to where they are asking their questions.
Quality over quantity
Nothing can hurt a brand quite like poor quality content can. As a developer, there is nothing more disappointing and frustrating than a top hit search result that doesn’t deliver. It’s that bullshit allergy.
I agree with Adam DuVander’s tips to quickly improve writing here:
For a developer, quality content is content that is easy to consume quickly. For that, you’ll want to think of the letter “F” as in the “F pattern.”
Yes, you should use AI
But don’t let the robot do all the writing! Unless you are using an LLM trained on your writing style, it’s not worth it for AI to generate an entire blog post for you. You will end up spending more time verifying technical accuracy, checking for plagiarism, and editing for style and originality than if you just wrote the first draft yourself.
However, do use AI to help you brainstorm, outline, and get unstuck. I find generative AI tools especially helpful when I need different options for titles and headings or when I need specific writing assistance such as breaking up a run-on sentence and conveying the same idea in a different time or style. Generative AI still can’t make the original creative connections humans can make. However, if you give the robots material to work with, they can offer us another perspective.
Developers are people too
Okay, so I am not the famous fantasy and science fiction writer of my childhood dreams, but I still get to professionally tell stories. While technical writing and technical content require a more specialized set of skills and a deeper level of precision and accuracy, it is still ultimately intended for a human audience.
Humans relate to stories – even if the story is steps one through ten of a tutorial. Remembering this will help you create content that embodies both the authenticity and technical rigor developers are drawn to.
Events and resources and other notable things
- Hey! PyBay is coming up in September 2024 and their CFP is open until 07/31!
- Developer Week is in February 2025 and their CFP is also open and closes 09/06! Both PyBay and Developer Week are in the Bay Area.
- I signed up for the Useless Fun AI Build-A-Thon – useless tech is right up my alley. Especially if it’s over-engineered.
Obligatory Streamlit mention
- It’s time for another showcase! Tomorrow 07/31! Sign up to come hear the scoop straight from the horse’s mouth.
- Here is some content I managed for the Streamlit blog: One is about how Streamlit sped up Community Cloud cold deployments with a Rust-based Python package manager. The other is about how to use Streamlit if you've never used it before. Your call to action should you choose to accept is the following: Please click on those links and share them with your network. (I can be real with you because you work in DevRel and you know what's up.)
Top comments (0)