Starting a blog is one of the best ways to advance your career as a software developer. Writing can help establish your name in your field of choice, can open doors to conference speaking opportunities, can earn you new job opportunities, and more.

But writing can be hard, especially if you’re a developer that doesn’t have much writing experience. In this article I’m going to share a few tips I’ve learned from writing technical content for the last five years. Hopefully you’ll find some of these tips helpful whether you’re just getting into the technical writing world, or whether you’re already a technical writing professional.

Let’s start with what I consider to be the single most important thing you can do when it comes to writing.

Tip #1: Write!

The hardest part of technical writing is the actual writing part. Although this is obvious, it’s easy to forget that writer’s block applies to technical writers just as much as it applies to authors of popular fiction novels. If you plan on consistently writing about software—whether it’s documentation or bug reports or framework comparisons—you’re inevitably going to struggle to see your content through from start to finish.

There’s no easy solution to this, but the single biggest piece of advice I have is this: just write. What I mean is, when you’re just starting to type out your thoughts:

• 1) Don’t care about grammar.
• 2) Don’t care about formatting.
• 3) Don’t care about writing elegant introductions.
• 4) Don’t care about planning a perfect table of contents or flow.

Just write. If it helps, pretend you’re explaining a concept to a friend sitting right next to you. You may end up writing nonsense, but you also might surprise yourself by just how coherent and conversational your stream of consciousness is. Experiment with writing in different locations to see what works best for you as well. You might find a certain places are more conducive to writing than others.

The desk I do most of my writing at. Not the world’s most impressive setup but it works for me.

When you’re writing, you need to constantly fight to fight the tendency to let perfection be the enemy of good enough. Imposter syndrome is just as real for technical writing as it is for software development—perhaps even more so—and no one is immune.

Personally, I’ve written some things I’m proud of and some things I’m not, but what I regret most are the article drafts that have died on my hard drive, or the article ideas that never materialized because I didn’t think I could write about a topic as well as someone else had.

When you start to feel like that, step back for a moment and remember that, with technical content, you’re not writing for a newspaper, a magazine, or for a novel—you’re writing for developers, and developers usually aren’t looking for world-class prose; they’re looking for straight-to-the-point content that tells them what they need to know.

Tip #2: Get to the point

Your average developer reads blog posts with the attention span of a gnat. Think of your own behavior when you’re looking for the answer to a compilation issue, or researching how to work with a specific API. You’re not looking for a novel with intricate detail and clever metaphors—you’re looking for an immediate answer.

Just to give you an example, this blog has an average session duration of 30 seconds, and an average of 1.08 pages per session—and most of the things I write take well more than 30 seconds to read 😄

The analytics data for this blog in May of this year. Note the low session duration and high bounce rate.

Have that in mind when you write technical content. If the title of your article is a question, give the answer right away. You can follow up your answer with as much detail as you’d like, and maybe background information on how you came to your conclusion—just don’t bury the answer 1,000 words into a blog post. This is technical writing, not a murder mystery.

Tip #3: Don’t assume knowledge

Regardless of what you’re writing, you’ll inevitably get readers from a wide variety of backgrounds and experience levels. While it’s very difficult to accommodate everyone, it’s important to try to explain what your topic so that most developers can follow along.

99% of #programming tutorials on the web pic.twitter.com/lnU08BjBgC

— Jonathan Shariat (@DesignUXUI) July 18, 2014

This doesn’t mean that you need to explain every single concept you use and every line of code you write. But it does mean that you should try to constantly read your writing from a beginner’s perspective, and provide context as necessary.

I like to use little asides to point readers at relevant background information. For example I might use something like this in a JavaScript article.

NOTE: The () => {} syntax in the following code is a JavaScript arrow function, which is fairly new to the JavaScript language. If you’re looking for more detail on what JavaScript arrow functions are and how they work, check out the Mozilla Developer Network’s article on the topic.

These asides are a great way to direct readers to relevant material without messing with the main flow of your article. You can use this same technique for introducing prerequisties at the beginning of your article. For instance, an advanced NativeScript article might include the following warning right at the beginning.

NOTE: This article assumes you have some basic knowledge of what NativeScript is and how it works. If you’re new to NativeScript, start by going through the framework’s getting started guide.

Overall the most important thing to keep in mind is you should always try to interpret what you write from other people’s perspective. And because that can be difficult, another thing you can try is having others read your work and give feedback.

Tip #4: Get honest feedback

Getting honest feedback on technical writing is hard. If you ask a random friend or coworker what they think of your latest blog post, they’ll probably just say that it looks good or is ok.

If you really want to improve your writing you need to find that blunt person in your life that won’t hold anything back. Bonus points if that person has copy editing or software development skills, but even getting honest feedback from readers with no technical background can be enormously beneficial.

For me that person is my significant other, who has no reservations about telling me when my articles are incomprehensible. For others that person might be a friend from college, a coworker, a teacher, or whoever.

If you’re having trouble finding someone I will give you two tips:

• 1) Try reaching out to the people behind the technology you’re writing about. If your writing is helping people using a specific project or framework, there are almost certainly people in that project’s community that are willing to help you out. Try asking for feedback in that project’s forum, blog, chat, or wherever.
• 2) Write for sites that employ professional editors and copy editors. Over my career I’ve written for Manning, MSDN, Smashing Magazine, and a few other sites, and each time I’ve learned something from the process. If you have interesting topics to write about, you’d be surprised how many publications would be willing to help you write a polished article for their audience.

Tip #5: Have fun?

Like most things in life, if you’re not having fun you’re not going to want to keep doing it. Writing is no exception.

If you approach technical writing like a mandatory essay from your 9th-grade teacher, then you won’t be writing for long. If you approach writing as a way to help others, document your thoughts, and let your personality shine through, you just might want to keep doing it.

One thing’s for sure: the tech world isn’t suffering from an abundance of writers right now, so there’s a lot of opportunity for technical writers to make a real difference. Have you solved a tricky problem lately? Try writing down your solution and explaining it to others. Found an issue in your favorite framework’s documentation? Try fixing it and sending a pull request.

The important thing is to find what you enjoy doing, because that’s what’s going to keep you writing and improving your skills.

Wrapping up

Writing good technical content can be hard, but it also can be extraordinarily beneficial to your career and personal development. I have the job I do today because of this blog I started five years ago, and I know many others with similar stories.

The most important advice I have for new technical writers is to just start writing without worrying about the consequences. Don’t worry about grammar, or formatting, or where to blog, or what others are going to think—just start writing. Over time you can start to refine the content you write, improve your grammar, and find your own style—but if you never get started none of that will matter.

NOTE: This article was inspired by an article on the same topic by Brian Rinaldi. It’s a good follow-up read if you found this interesting.