Writing Tips for Software Developers – How to Become a Tech Writer – You might think that software development is all about writing code, but that’s not true. A huge part of the job is communicating with others. And as we all move towards more remote work, written communication is becoming increasingly important. I’m happy to say that it’s gone really well, and my company was recently featured on TechCrunch for our technical writing work.
In this post, I want to share a few of the writing tips I regularly share with other software developers. These will help you get over the resistance that all new writers face and hopefully give you the confidence to start writing sooner rather than later.
1. Start by Writing About What You Know
“No one started off as a great writer. Start writing about the things you currently know and share them with the community. You’ll be surprised how many lives you’ll impact.” – Eze Sunday, Software Developer and Technical Writer
In order to become a better writer, you have to do it more often. This is true of any skill, but it can be especially hard with writing because you can’t just string random words together on a page. You have to write about something.
The most common piece of advice for overcoming this barrier is to start writing about things you already know.
He went on to point out that even if the topic has been written about extensively already, your piece can be different. “Writing is about perspective and as unique as we all are as humans, so are our perspectives.”
Eze Sunday reiterated this idea: “Yes, there are a lot of articles. But, there are not a lot of good articles that will explain things the way you would love it to be explained to you if you were just starting out.”
2. Focus on a Few, High-Quality Pieces
“Quality trumps quantity,” James Hickey told me. “Focus on writing high-quality articles vs. a bunch of ok articles…No one will be impressed when your content is just ok.”
James is a senior .NET Developer, Microsoft MVP, author, and speaker with eight young children at home, so finding time to write is always a challenge. His solution is to be very selective about the writing he takes on, but when he gets into a topic, he goes deep.
You can see this in his work, like this one on e-commerce data models that hit the front page of Hacker News.
I’ve similarly found that some of my most popular blog posts are the ones that went really deep into a topic.
For example, one of the most popular pieces on my personal blog is this 4,500-word guide to API development. I’ll admit, I write a lot of shorter pieces, but there’s something to be said for being thorough.
3. Perfect is the Enemy of Good Enough
On the flip side, don’t let your drive to produce the best content possible stop you from hitting the “publish” button.
Dan Moore, who runs Letters to a New Developer and Developer Relations at FusionAuth, offered up this suggestion:
“Perfect is the enemy of the good enough. To combat that, I like to timebox and then publish even if the piece isn’t perfect…Maybe your post won’t hit the front page of Hacker News, but I guarantee that if you don’t publish it, no one will read it.”
Many new writers get too caught up in the mechanics rather than the structure and organization of their ideas. To be honest, readers are more likely to forgive spelling and grammar errors as long as they can follow your logic.
“It’s easy to get caught up in trying to make your writing the best it can possibly be: with perfect grammar, great sentence structure, etc. I’ve used tools like Hemingway Editor to make my writing ‘technically correct’ and when I re-read my work, it comes out sounding stale and like it was produced by AI.”
4. Set Aside Time to Write Regularly
“You’ll want to treat [writing] like any habit and set aside time. One thing I’ve found useful is to write first thing in the morning, maybe even get up a little earlier. I was not a “morning person,” but still found this to be when I had the most writing energy. Nothing else at that point has taken my mental energy.”
Personally, I block writing time on my calendar every week. I found that I do my best work when I’m focused on writing for 4-8 hours rather than trying to cram it into little breaks throughout my day. Of course, not everyone works the same way. Stephanie Morillo, a Technical Communications Specialist, makes writing fit into shorter windows.
Writing Tips for Software Developers
“I use timeboxes: if I know I have to write a talk or a blog post, I’ll set aside multiple 30-minute blocks throughout the course of a day or a few days and will sit down and write.”
She pointed out that these smaller chunks of time are more realistic for her schedule and it allows her to make progress and increase her output: “If you write 10 words or 100 words or 1,000 words in a day, you’re still making progress toward your goal.”
Another strategy is to make writing a daily habit. Alex Lakatos, who runs the Developer Avocados newsletter, did a daily writing challenge for part of last year:
The point is that every person is different and there’s no one-size-fits-all approach to setting aside writing time. “The biggest thing is finding a time where your brain can focus and has the creativity to actually get your thoughts down in a coherent way,” Keanan Koppenhaver told me.
5. Manage Your Expectations
“It is, of course, nice to have your writing read by others, but there’s tremendous value in writing for yourself, and you’re guaranteed an audience. So, write for yourself first and foremost.”
It’s hard not to get caught up in the thrill of having something you write go viral. I’ve published hundreds of blog posts in the past 10 years and just five of them have hit the front page of Hacker News. This is not an impressive hit rate. Writing Tips for Software Developers
“Keep a journal and write notes about work, your day, your life, your emotions. Journaling gives you the opportunity to write without being self-conscious because you’re not writing with an audience in mind; you’re doing it for yourself.”
Finally, it’s important to keep your goals in mind when you start writing. Are you simply writing to record your own learnings? Are you trying to promote a book or course or product? Do you need to get paid to write or is it just for fun? being honest with yourself about these expectations is critical. “Decide whether it’s a side thing or a main thing,” he told me. “You can make either work, but you’ll want to set your expectations appropriately…There are a lot of ways to use writing in an engineering career.”
As you won’t get better at something unless you start doing it. Whether you want to use writing to advance your career, make side income, or help others in the community, you have to start doing it more if you want to get better.
What tips do you have for software developers who are looking to become better writers? I’d love to hear from you on Twitter if you’ve got something to add!