How to Write Better Technical Content

I recently spoke to the CTO Craft community about building a software engineering team blog. Towards the end, we got into some specific writing tips for software engineers who struggle to create strong technical content.

I’ve been writing online since at least 2010. I don’t remember if I published anything before that, but that’s the date of the oldest post I could find on my old Blogspot. In that time, my interests have changed a lot, but I’ve published relatively consistently along the way.

Most of my writing has been unpaid work done purely because the topic interested me, but in the past year since I started Draft.dev and turned writing into a career, I’ve started to think more critically about what makes good technical content.

In this post, I’ll share my tips for technology professionals looking to write better content. Most of these tips will apply to anyone interested in writing, but they’ll be especially geared towards software developers as that’s my background.

This is a long post, so if you’d like to hop around, here’s what I’ll cover:

1. Don’t Expect to Be Very Good
2. Be Consistent Anyway
3. Writing is Organizing
4. Write as You Speak
5. Prove Your Point
6. Invest in Interesting Ideas
7. Tell People

1. Don’t Expect to Be Very Good

“The skill and ability involved in writing sentences is generally underrated, and assumed to be a much more universal capacity than it really is…Most people know that they couldn’t write even a very bad song, or paint a picture, and understand their limits in that regard. On the other hand, everybody can write prose after some fashion, so it is not quite clear to them that they don’t actually have the ability to do it to a professional standard. That ability is quite a rare one.” - Philip Hensher, Professor of Creative Writing at the University of Exeter

By the time you graduate from high school, you’ve probably spent a fair amount of time writing. You might think you’re pretty good at it, but as soon as you dust off that old keyboard and start putting the proverbial pen to paper, you’ll quickly realize that writing is harder than it looks.

The Gap

The problem here is what Ira Glass calls “the gap:”

“All of us who do creative work … we get into it because we have good taste. But it’s like there’s a gap, that for the first couple years that you’re making stuff, what you’re making isn’t so good, OK? It’s not that great. It’s really not that great. It’s trying to be good, it has ambition to be good, but it’s not quite that good. But your taste — the thing that got you into the game — your taste is still killer, and your taste is good enough that you can tell that what you’re making is kind of a disappointment to you.” - Ira Glass

This gap is especially problematic for technical writers like software engineers because the amount of information you have in your head is exponentially more than the amount you’ll be able to get onto a page in an hour. Software engineers who are new at writing get frustrated easily because they know what they want to say, but lack the language, typing speed, or organization skills to write about it well.

Your first 100 blogs, videos, posts, Tweets, lives, podcasts, creations will probably all be rubbish

Get over that and get to it, get past that first 100

Hardly anyone will see it anyways, it’s practice for when they do

That’s the price you pay for creating

— The BKH - Show don’t tell ™🤝 (@thebkh) December 12, 2020

Just remember that everyone starts out as a beginner, and you can’t create skills overnight.

Find an Editor

Once you accept the fact that your early writing won’t be that good, it takes a weight off, but how do you actually start to get better?

A few years ago, I started dabbling in freelance writing. I remember thinking I was a pretty good writer, but my first draft back from an editor was riddled with suggestions. Some were simple formatting issues, but many were structural. I had to go back and rewrite large chunks of the piece to get it right.

If you aren’t ready to submit work to an editor yet, you can always enlist a friend for help. Even non-technical editors can help you improve your technical content. The best editors will be able to tell you when an idea you present doesn’t make sense or the piece is poorly organized.

2. Be Consistent Anyway

Many great projects go through a stage early on where they don’t seem very impressive, even to their creators. You have to push through this stage to reach the great work that lies beyond. But many people don’t. Most people don’t even reach the stage of making something they’re embarrassed by, let alone continue past it. They’re too frightened even to start. - Paul Graham

The key to getting better at writing is to do it consistently, even if you’re not that good at first.

Write Every Day

One way to write more is to write every day.

In 2017, I made a commitment to write every day. I didn’t hit that goal, but the year was still my most productive year as a writer to date. I wrote a book, updated many old posts on my personal blog, got paid to write a few pieces as a freelancer, and contributed to my company’s blog a few times. I don’t keep a word count (to me, that’s sort of like tracking how many lines of code you write), but I’m sure it was over 50,000 words.

“Measuring programming progress by lines of code is like measuring aircraft building progress by weight.” - Bill Gates

My friend Alex Lakatos is working on a similar effort right now:

💡On average, it takes 66 days to form a new habit. There's 65 left until 2021, so how about we start early on those New Year Resolutions?

I'll start: I'm trying to publish content consistently, so I'll try to write a minimum of 100 words a day for the remainder of the year. pic.twitter.com/M0dHrJ36ef

— Alex Lakatos 🥑🇬🇧 (@lakatos88) October 28, 2020

I don’t think you have to write every day forever to get better, but it will dramatically accelerate the speed at which you improve.

Block Time for Writing

“Because of technology, some people feel distracted – they can’t focus, that they can’t pay attention to what’s in front of them because their minds keep jumping around. They aren’t getting their work done; they’re not paying attention to their kids.” - Gretchen Ruben

A few months ago, I realized I wasn’t getting as many of the important things done as I would have liked. I started blocking my time off each week in 4-hour increments, focused on one thing I want to get done. Now my calendar looks like this each week:

I want to devote 8-12 hours per week to writing consistently, so I literally block my entire Thursday and Sunday off for it. During blocks where I have meetings, I focus on sales and marketing tasks that are quicker and don’t require the same level of flow.

If you don’t do this, it’s way too easy to fall into the trap of endlessly checking email, scrolling through your Twitter feed, or playing Candy Crush instead of creating great content.

Deliberate Practice

“While regular practice might include mindless repetitions, deliberate practice requires focused attention and is conducted with the specific goal of improving performance…In the beginning, showing up and putting in your reps is the most important thing. But after a while we begin to carelessly overlook small errors and miss daily opportunities for improvement.” - James Clear

Once you make writing a habit, you have to figure out how to actively improve your craft. Creating great technical content requires focused practice with increasingly difficult tasks.

The mental model I like is called the zone of proximal development. The idea is that you will learn the most by maximizing your time doing tasks that are just outside your level of mastery.

James Clear includes several examples in his essay on deliberate practice, but the most relevant to writing technical content is Benjamin Franklin’s story:

“When he was a teenager, Benjamin Franklin was criticized by his father for his poor writing abilities. Unlike most teenagers, young Ben took his father’s advice seriously and vowed to improve his writing skills.

He began by finding a publication written by some of the best authors of his day. Then, Franklin went through each article line by line and wrote down the meaning of every sentence. Next, he rewrote each article in his own words and then compared his version to the original…Franklin realized his vocabulary held him back from better writing, and so he focused intensely on that area.

Deliberate practice always follows the same pattern: break the overall process down into parts, identify your weaknesses, test new strategies for each section, and then integrate your learning into the overall process.”

The great thing for people creating technical content is that breaking down and rewriting existing tutorials is a fantastic way to both learn the technology and hone your craft as a writer.

Don’t Overcomplicate It

“Our life is frittered away by detail…Simplify, simplify.” - Henry David Thoreau

I really appreciate this diagram on writing by Doug Arcuri, but I think it overcomplicates the process for most new writers. While organization is important in writing (more on that in the next section), don’t let it overwhelm you.

The most important part is to start.

3. Writing is Organizing

The first two points above have been a little bit philosophical, but I want to spend the rest of this post getting tactical. I’m going to start with organization.

Most new writers don’t realize that organization is such an important part of writing. This is especially true in technical content where you’re trying to convey or teach a topic to a diverse audience. You want to give new readers the ability to build up to difficult topics while giving experienced readers the ability to skip to the parts they care about. The only way to serve such diverse readers is to invest time in organizing.

Start Every Piece With an Outline

Your 7th grade English teacher probably taught you to start with an outline, but by the time you got to 12th grade, you probably skipped that step to save time. Some writers think they know the topic well enough to skip outlining, but I can tell you it’s a really bad idea.

The outlining phase is where you prioritize ideas, identify weaknesses in your knowledge, and crystalize your main points.

I’ve also found that starting from an outline speeds up the writing process dramatically. With a well-thought-out outline, writing becomes the mere act of connecting the dots. Without one, it’s an unintelligible mess.

How Specific Should Your Outline Be?

My rule of thumb is to write an outline that covers all the H2 and H3 tags on the page.

Don’t stick to the outline like a rule-book; it’s more like a starting point. I often discover new ideas as I’m writing and need to move things around to accommodate them.

If you’re writing technical tutorials, you should create the demo application and outline the steps before you start writing the rest of the content. If you do it this way, you’ll find the writing part is very quick. It often takes me less than two hours to finish a 1500-word tutorial after I’ve written the code and outline.

Organization Methods

If you’re a new technical writer, it’s probably hard to know how to start organizing technical content. There are four commonly accepted methods that I push people towards:

1. Chronological - Tutorials are typically organized from first step to last.
2. Importance - When presenting multiple options or comparing factors between tools, it’s usually a good idea to order them by importance.
3. Problem and Solution - I like framing posts around problems and solutions when they’re aimed at technical decision-makers.
4. Roundups (aka Listicles) - This method works well when you want to make information more scannable.

There are probably optimal organizational systems for different kinds of posts, but honestly, just having any system will make your writing better than most.

4. Write as You Speak

“Your writing should sound like you. Your vocabulary, your cadence, your syntax, your dialect. Your verbal idiosyncrasies. Friends and colleagues should be able to hear your voice in their heads as they read. Communication is a relationship, and to develop an authentic relationship with your reader, your writing – like your speech – should convey not only your opinion, but also a bit of your personality.” - Sarah Chauncey

I used to write technical documentation for Siemens medical imaging equipment, so I read and wrote a lot of dry documentation. That said, not all technical content needs to read like a user manual.

Blogs are great because they give you carte blanche to create your own voice. That said, adopting a specific voice for writing is really hard, so new writers should keep it simple and write like they speak.

Build Up to Each Concept

The other problem that subject matter experts encounter when they start writing is they forget most readers won’t be as knowledgeable as they are. Good technical content is correct and uses industry-standard terms without overwhelming new readers. The trick is to build up to each concept as you deliver it.

The way I do this is by creating an outline that starts with no assumptions. For example, if I were writing an article about deploying Python workloads to Kubernetes, here’s what I’d start with:

• What is Python?
• What is Kubernetes?
  • What is a Kubernetes cluster?
  • What are the relationships between Kubernetes and containers?
• Why deploy Python to Kubernetes?
• How to deploy a Python web application to Kubernetes:
  • What is a workload in Kubernetes?
  • How do you prepare a Python application for Kubernetes?
  • …

While the focus of the article is on deploying a Python application to Kubernetes, I’d probably devote 2-3 paragraphs explaining the basic terminology. Then, I’d link readers to more comprehensive resources (like the documentation) to let them explore these topics in more detail.

This might seem like overkill, but an experienced reader will simply use the headers to skip down to the portion of the technical content they need. This extra context will only help people who are new to Python or Kubernetes ramp up to the meat of the article.

It’s admittedly hard to do this without shaving the yak, but you’ll get better at it the more you write and get feedback on your writing.

Can You Be Too Casual?

Most writers tend to be too formal, but since I started editing more in the past year, I’ve realized that some fall towards the other extreme instead.

The important thing is to know your audience and the publication you’re writing for. If it’s your personal blog, you can be as casual as you want. If it’s for your company’s blog, you might want to make it a little more formal.

My rule of thumb when writing technical content is to pretend you’re in a business meeting. If you wouldn’t say it in front of your boss, you shouldn’t write it in public.

Self-Editing

“Writing without revising is the literary equivalent of waltzing gaily out of the house in your underwear.” - Patricia Fuller

Editing is an entirely different skill than writing. I used to assume that anyone who could write could also edit, but I’ve since backed off that view. Writing is the big-picture process of organizing, researching, and molding ideas together. Editing is getting the nitty-gritty details right and asking if this whole thing even makes sense.

That said, good writers do at least a little bit of self-editing.

I do two things for every post I write before I hit publish:

• Wait a few hours, then read it out loud - This helps me catch logical omissions and poor organization. Waiting a few hours helps me get a fresh perspective that I couldn’t get right away.
• Run it through Grammarly - This helps me catch little details, misspellings, and wordy sentences.

5. Prove Your Point

“The best way to show that a stick is crooked is not to argue about it or to spend time denouncing it, but to lay a straight stick alongside it.” - D.L. Moody

One of the few things I remember from my high school English class was my teacher’s insistence that every claim be backed up by a source. For some reason, that stuck in my future engineer’s brain, and it’s become a great asset now that I write for a living.

Good technical content must be correct, so I pretend that my readers are all ornery skeptics hoping to poke holes in every statement I make.

There are three ways to add evidence to support your claims as a writer:

1. Research - Academic research typically has the highest bar, but business surveys or secondary research are sufficient for most informal technical content. Unfortunately, a lot of people don’t verify the research they use very carefully. This leads to a lot of technical content backed up by dubious claims taken out of context.
2. Quotes - I like quotes for a few reasons. They help break up long blocks of text by injecting an authoritative source, and they can add the weight of celebrity to your ideas. Again, be careful with verifying quotes.
3. Examples - People really like stories. While this can get naive readers into trouble, it’s helpful ammunition for writers. Personal experience or relevant anecdotes also help strengthen your claims.

6. Invest in Interesting Ideas

“Do not worry. You have always written before and you will write now. All you have to do is write one true sentence. Write the truest sentence that you know.” - Ernest Hemingway, A Moveable Feast

You probably have three or four ideas that you find interesting right now. For example, I’ve been thinking about the expert fallacy, what’s coming in the 2020s, and the idea that engineers are either farmers or pioneers.

I’ve written about these topics already, but something I never realized until this year was that as a writer, you can write about the same topic twice.

In fact, the best writers come back to the same few ideas repeatedly throughout their careers.

“The key is identifying all of the smaller components that go into the same topic and then fleshing each of them out until they are large enough to make up a complete piece of writing on their own.” - Louise Truscott

I can’t remember where I first heard this idea, but lately, I’ve been trying out ideas on Twitter. If they pick up a little traction, I’ll bring them into conversations and keep an eye out for other writing on the topic.

If it seems like others are interested in the idea, I’ll write a short bit about the topic in my email newsletter or on Reddit.

Finally, when I’ve run the idea through a few people and really honed it, I’ll compose a blog post on the topic. Here’s how this worked for my post on experts I mentioned above:

The idea started with a few tweets. People responded to them, and I refined the idea during a couple of conversations and a podcast I recorded for a friend. I read more from other writers on similar topics and eventually summarized my thoughts in my weekly email newsletter. Finally, I constructed the final product: a 2500-word blog post called The Danger in Listening to Experts.

Nobody is Truly Original

Written content doesn’t have to be completely original. A lot of writers get paralyzed when they can’t come up with a novel idea. Andy Haskell talked about his perfectionist tendencies in a blog post earlier this year:

“My perfectionist tendencies made it take forever to get a new post out the door, and caused me to feel like my content was going to be nothing new that people couldn’t already Google for. That narrative in my head left a lot of unfinished blog posts piling up.” - Andy Haskell

The truth is that all ideas are really mashups of existing ideas. That doesn’t mean your perspective on a topic won’t contribute to the world. You probably know many things that other software developers don’t know. When you create technical content online, you might just write it in a way that resonates with someone else. The opportunity to teach someone - even if the concept isn’t original - is enough to motivate most writers to power through at least a few blog posts.

Stay Open to Inspiration

“Most of what I “write” doesn’t even happen on the page. It happens while I’m away from the computer, when I’m in the line at the grocery store, waiting at the airport, or speaking with friends.” - David Perell

Ideas come from without, not within. That means you have to get out into the world if you want to come up with good ideas for technical content.

Software engineers do this by tinkering with new frameworks and languages. Product managers might try new organization tools. Designers might have conversations with artists for inspiration.

7. Tell People

“Distribution is the secret of the most successful blogs. Writing well is the cost of entry, but distribution takes you to the top.” - David Perell

I’ve been refreshing blog posts on my personal blog for the past couple of months. To illustrate the power of distribution, here’s the traffic on one of my old posts over the past year:

I wasn’t actively promoting the post, but it was bringing in 60-120 pageviews per month thanks to Google searches. In November 2020, I decided to update the post and re-share it on social media. It got some upvotes on Hacker News and Reddit, and ended up bringing in 1204 pageviews that month alone.

Simply sharing this blog post led to a 12x increase in traffic to it over the course of a month. This is why writers should learn to share their content. If you want people to read your work, promoting it is essential.

If you’re looking for a checklist of ways you can promote technical blog posts, I put mine up on the internet earlier this year. Every piece of content is different, but this should give you a good starting point.

Final Thoughts

Writing great technical content won’t happen overnight. If you expect to be good at it from the start, you’re likely to be sorely mistaken, but stick with it. Writing is a great way to increase your influence and get noticed for your work.

Once you start writing, build a process for capturing and refining your ideas. Good technical content is almost always an amalgamation of existing concepts, but the more you compile these ideas, the better you’ll get. Finally, tell the world when you write! Your knowledge is valuable, and it’s very rewarding to have people share and learn from your content.