Writing Advice for Developers

There are many resources to teach you how to write better, but barely any apply to developers. I’ve consumed dozens of books, guides, courses, and podcasts on writing, but most advice is helpful only for novels or memoirs. So to save you time, I’ve compiled what I’ve learned from those resources and my own experience writing for developers.

Whether you’re just starting to write articles or already blog regularly, you’ll find the practical tips and exercises helpful. You’ll learn how to create a writing habit and which low-effort exercises can help you practice and hone your skills. You’ll also learn that writing becomes much easier when you separate it into two phases. I’ll also drop some of my favorite resources so you can develop your non-fiction writing skills further.

Why Write as a Developer?

When you practice writing, you practice communicating. Being a strong communicator is an advantage in any field, particularly development.

When you get better at writing, communicating with your coworkers becomes easier. We live in an async world where clear and concise docs are highly valued. Through writing, you can keep institutional knowledge and make onboarding easier. Prolific writers are assets to their companies.

Through writing, you can grow an audience and help others. The better your writing, the more likely people will read your entire article and share them with others. Your audience makes you stand out from the pack and can lead to opportunities like jobs, speaking gigs, and contract work.

Your writing will showcase your knowledge and expertise even if you have yet to gain an audience. It’s a great way to show potential employers or clients you know your stuff.

Practice and Improve

For some, writing can be as daunting as public speaking, and we’ve all felt the frustration of Writer’s Block. We’ll learn to develop a writing habit and some practice exercises to help us push past any resistance.

Develop a Writing Habit

Habits are the best way to improve at something. To get better as a writer, you should write every day.

Set small, realistic goals. Try writing for five minutes or 200 words daily. Consistency over weeks and months is more important than writing a thousand words today. It’s not about writing one article. It’s about becoming a writer.

Create a routine where you write at the same time every day. Even better is if you pair this habit with something you do every day already. For example, “When I have my morning coffee, I’ll write 200 words.”

If you’ve ever tried to start an exercise routine, you know that if you don’t schedule time for the habit, it won’t happen. Like you’d schedule a morning run, schedule your writing time, and stick to it.

Writing Prompts

All writers deal with the voice telling them, “You have nothing to write about.” You have plenty to write about, but starting from nothing is hard. That’s where writing prompts come in handy. For example:

• What are your tips for debugging and troubleshooting?
• “Everyone forgets about __ but it’s super important!”
• What future feature or technology are you excited about?

I’ve put together a full list of writing prompts for developers. Grab any of these prompts and go for it.

If none of them resonate with you, spend your writing time today coming up with your own list of topics or prompts.

Freewriting

Freewriting is a form of practice where you write about a topic without stopping. Set a timer for ten or ten minutes and write, letting words flow with no filter and no editing. Don’t backspace, don’t fix typos, and don’t rewrite anything. You’re just trying to get as many words on a page as possible.

Don’t try to make this writing good. Freewriting is about quantity, not quality. It’s one of the best ways to defeat writer’s block because you’re not staring at a blank page. You can always come back later and edit it into something usable.

Copywork

Copywork is what it sounds like: you copy someone else’s writing word for word. Not to be confused with Copywriting, it’s one of my favorite ways to practice or start a writing session.

When an artist is learning to paint, they’ll copy the work of famous artists. It allows them to try on someone else’s style and understand how they crafted the piece. Developers look through open-source repositories to learn good coding practices. You can use the same principle with writing.

Find a great article from your favorite dev writer. Start at the beginning and copy it word for word, comma for comma. Pay attention to the details. How are things structured? What words do they use often? How are they showing personality or style? Stop every few paragraphs and take notes on the side of what you’re noticing and liking.

You won’t publish this copywork; it’s just for practice.

Copywork is an excellent pre-writing warmup: words are already flowing, and your brain has fresh ideas to bring to your next piece.

Read More

If you want to become a great writer, fall in love with reading. While reading anything will help your writing, you should consume what you’re trying to create. If you want to write tutorials, read one tutorial a day. If you’re going to write thought pieces, add them to your reading list.

It will be easier to write high-quality blog posts if you’re consuming TikTok videos or tweets.

Two Phases of Writing

There are two phases to writing: Creation and Editing. Things go so much better if you focus on one at a time.

Too many people want to do both at the same time. They want to create the perfect sentence the first time. To edit the sentence as they’re writing it, waiting for that perfect word to come to them.

Imagine yourself as a potter. Creation is kneading your soil and water to produce clay. It’s coarse and physical. Editing is when you carefully sculpt the clay into a vase. It’s delicate and methodical.

Don’t worry about the shape of the clay when you’re producing it. Trust your inner sculptor.

By dividing the task in two, you can let the creative side flow freely, knowing your critical side will come through to tidy up later. Let’s first get something on the page.

Phase 1: Creation

It’s time to create our clay.

When you’re writing your draft, ignore the voice that tells you the sentence isn’t good enough or you don’t know how to start. Just put anything down and keep the words flowing. Try your best not to let your fingers stop hitting the keyboard. Don’t get critical; create.

This phase is very similar to Freewriting in its approach. The first draft will be intentionally crappy. You need to get the ideas out on the page.

Let’s look at some techniques to help you in the creation process.

One-Line Outlines

Following the one-sentence per line rule with my outlines has had a massive impact on my writing.

With the one-sentence rule, you limit your sentences to one line and hit enter with each new sentence. It helps you evaluate each sentence on its own. Your points are easier to find and shift around so you can build the best structure for your article. You also guarantee you get one idea per line, forcing you to be clear.

Like wet clay, keep your outline and early draft malleable to make for easy reshaping in the editing phase.

Skip the Introduction

The introduction is often the most challenging part, so I usually skip it and focus on writing the rest. Writing the introduction is much easier after I know what I’m introducing. I wrote the introduction last for the article you’re reading now, and it went through about seven revisions.

Don’t Research Yet

Avoid falling into the research trap during your creation phase.

I get pulled down internet rabbit holes whenever I stop writing to research something. To keep my creation time uninterrupted, I research as much as I can beforehand or leave notes for what to research later.

It’s okay not to have the correct information when you’re drafting. Your thoughts and ideas might change once you research later, but task switching will kill your flow. It’s crucial to keep the words flowing.

I use triple parentheses in my articles for things I want to return to later. If I wanted to find a reference or some stats, I’d put (((Find stats about this))). Then as I’m editing, I search my document for (((. It’s the writing version of a TODO in your code.

Phase 2: Editing

Now that we’ve created our clay, it’s time to shape it.

Editing is where the real work takes place. It’s where you clarify what you’re trying to say. It’s where you check to ensure the sentences flow together and are easy to read. It’s also how you reassure yourself in the creative phase that the crappy first draft isn’t going to see the light of day.

Please don’t skip this phase.

Cut, Cut, Cut

More dev writers need to edit their work. I don’t mean spellchecking or Grammarly; I mean really editing. The kind of editing where you’re rewriting most of your paragraphs and slashing at least 30% of your rough draft.

Cutting unnecessary text is kindness to your reader. You’ll save your reader time and get your message across faster. Don’t dilute your message; be clear and concise.

I often turn paragraphs into single sentences or delete them altogether when editing. Multiple sections with the same message get combined into one.

Read it out Loud

Read your work out loud, and I bet you’ll find a sentence that sounds strange. Your ears will pick up on awkward sentences that your eyes missed.

Titles, Intros, & Outros

Pay special attention to these three parts when editing.

Titles are the most critical part of an article, hooking your readers and making them click. It doesn’t matter how good your writing is if no one ever clicks it. Compelling titles utilize the Curiosity Gap. Compare these two titles: Why Chakra UI is Incredible Most Next.js Projects Use These Ten npm Modules

Which of these made you more curious? The second creates a greater curiosity gap, encouraging you to click to discover those modules.

I highly recommend this video on creating click-worthy titles.

After the title, the second crucial part is your intro. Intros should let the reader know what value they’ll get from your article. It’s great if they can add some intrigue that entices me to continue reading.

Last but certainly not least is your conclusion. Most people don’t put a lot of care into closing, but it determines how people feel about your article.

Movies and TV series are often judged by how they end. The last 15 minutes of a movie can spoil the 120 that came before. You might think you take an average of every minute, but that’s not how we create memories.

This is because of something called the Peak End Rule. This says we form memories of things mainly around their climax and how they end. A lackluster ending makes readers remember a lackluster article.

Ask for Feedback

Having friends willing to give you honest feedback on your writing is invaluable. Ask them for feedback on specific points. I like asking where they were highly engaged and where they got bored.

Simplify your Sentences

Your topic might be complex, but your sentences shouldn’t be. Edit your article so readers have no problem understanding what you’re saying. Keep each sentence to one idea.

Here’s a great example from Julian Shapiro. Complex sentence:

“The obstacle facing media organizations is charting an economically sustainable course through a landscape of commodity journalism.”

Rewritten for simplicity:

“News companies are struggling to stay in business because anyone with a Twitter account can report the news now. The news has never been more of a commodity than it is today.”

The second version is longer but much more clear.

Writing Tools

When editing, everyone should run their writing through Grammarly. Its free version is excellent, but get the premium version if it’s within your budget. It advises on spelling, grammar, punctuation, sentence structure, vocabulary improvements, tone, and writing style.

ChatGPT is emerging as a writing tool that can help you in some aspects, but I’d recommend not using it to handle the bulk of your writing process. When I write, I want to improve my skill at explaining things. If I offload all of that to AI, I don’t get any of the benefits of having written.

Use ChatGPT before writing to brainstorm ideas or help with your initial outline. After editing, ask it to give you feedback and find areas of improvement in your article.

Remember, these tools are guides. Grammarly and ChatGPT sometimes need to be corrected, so check over everything they recommend.

Wrap Up & Resources

Applying these tips and exercises will enhance your writing skills and make you create more consistently. Developing good writing habits and splitting the writing process into two phases will make blog posts more manageable. Through writing, you’ll have clearer thinking, more opportunities, and a greater impact on your network.

Keep learning with some of my favorite books and guides on non-fiction writing.

On Writing Well - William Zinsser I’ve read this one through dozens of times. His other book, Writing to Learn, is worth a read, too.

The Elements of Style - Strunk and White Great to have nearby when you’re writing. It’s a concise 100-page guidebook that helps you with the technical aspects of writing in the English language.

Writing Handbook - Julian Shapiro An excellent guide on writing that goes into deep detail—more for people who want to write long, epic articles. I highly recommend you go through and read everything he says, especially the Practice section.