How to write better technical content
I was on Twitter recently when I came across these two tweets about words to avoid in technical content:
Ben and Kurt are totally right. But it got me thinking: “What are the foundational concepts behind good technical writing?”
Write with a distinct goal for your audience in mind
What do you want your audience to be able to do after reading your content? Let’s say I’m trying to write a guide for Github. My goal is for my readers to create their first repository and make a commit. That means I want to convey only the information necessary to get my audience up and running. I should avoid explaining in depth the origins of git or the difference between HTTP cloning vs SSH. My content piece should reflect the goal, something like “Getting Started with Github”. To write with that level of focus and clarity, it brings us to my next point:
Know your audience persona
Who do you think the audience is for a Getting Started on Github guide? It could be college students who don’t have industry experience. It could be experienced users who are migrating over from GitLab. It could be really old school users who used FTP for code delivery instead of a repository. These are all personas who could be looking for a Getting Started guide, but the content for them would all be drastically different.
One big plus in my book is when the headline has the persona. This makes it super easy for me (the developer) to sift through content and find the thing I’m looking for. Using the previous example, an ideal headline could be:
Getting Started on Github as a College Student
Going one step further, I could interview a few college students and figure out what they understand about Github and what the biggest value prop I could provide is. Maybe I discover that college students don’t know that git is different from Github or that they think Github is only for collaboration. These are all learnings about the persona that can help me write more helpful content.
Conclusion
Overwhelmed? You’re not alone. Writing high quality technical content is extremely time consuming, but it’s incredibly rewarding! Remember that the main goal of technical content is to help your audience. By knowing who they are and what their goals are, you can meaningfully help real people. My last takeaway: It’s more fun being super helpful to a smaller niche group than write a generalized content piece for “any” developer.
