Mastering the Art of Technical Writing: Here’s What Has Worked for Me So Far

It's been a little over a year since I made a serious commitment to producing technical content. It was primarily for my Medium publication Event-driven Utopia, which I launched last December, which has grown up to 700+ followers today. The rest is related to my work and other engagements.

My writing process had its fair share of setbacks, victories, and lessons. I'm not an award-winning author, or I did not author a best-selling book. But, as I'm reflecting on my journey so far, I want to share the things that worked for me, hoping that would help you somehow to succeed as a technical content creator.

In this post, I talk about coming up with a process for content production. That mainly involves planning your content, which includes choosing your audience and content type, scoping out the and structuring the content before even writing a single word. 

The rest of the series will go into the mechanics of the process that details the writing techniques and post-publication stuff. 

Who can benefit from this guide?

Here, I'm talking specifically about the art of technical writing, not creative or copywriting. So people in the following roles would benefit from this post.

• Developer relations engineers, developer advocates, and evangelists plan to create educational content for developers.
• Product marketing folks to craft content around their products.
• Solution engineers and solutions architects plan to publish their experiences in the field.
• Technical writers to carry out their day-to-day operations.
• Software developers to document the lessons learned on the job.

Where to start? finding a systemic way for writing

In the beginning, I often came up with a random idea, gave it a few weeks for researching, sometimes procrastinated, and finally completed the writing after taking about a month. It was all random, didn't have a process, and nothing serious about it. 

Back then, I was trying to figure out a process to produce content consistently. The more I wrote, the more I felt closing into figuring out a system.

I believe I have a solid process today to churn out content weekly. That didn't come to me overnight, but it's a result of continuous writing over a year.

So, let me share my writing process with you.

The process at 33,000 feet high

My process can be broken down into three major stages as follows.

The planning stage is all about deciding what you want to write and how you want to structure the content. The delivery stage focuses on the writing itself, how to enhance the delivery, and publishing the finished content. The post-delivery stage contains the activities you can do after your content is alive. 

I will dive deep into each stage in the coming sections. I will call out specific areas you want to pay attention to in each section. Let me start with the planning stage.

The planning stage

In the planning stage, you decide what to write and how to write about it.

Pick your audience and content type

Not all content is made equal. Also, not all your readers are the same. Remember that as rule number one in content production.

Before you write anything, you must think and decide whom you should address and what content they expect. My colleague, Mark Needham, introduced me to the Diátaxis framework that classifies content into four areas.

Each area answers to a different user need, fulfill a different purpose, and requires a different approach to its creation.

Your readers can be experienced professionals with technical knowledge, business decision-makers who are not tech-savvy, or beginners trying to grasp the basics. Think and pick your audience persona before you craft content. 

For example, if you came up with an idea of why Kubernetes is revolutionalizing modern application delivery, it'd be better to target business decision-makers and experienced professionals. The reason being, that audience already understands the basics, and you don't have to start from scratch. Then go for a content type that talks about Kubernetes at a high level, rather than taking a deep dive.

Scope out the content and give it your most focus

Once you have figured out the audience and content type, you should decide how deep you can go into the content.

Let's say you are going to write about stream processing. Since it's a vast area to be explored, it will take more time for you to learn and master it before writing. At that point, I suggest you not go after domains that require extensive research that could take about months to complete. Instead, focus on a smaller scope of the domain you are most comfortable with and have the confidence to finish it within two weeks. 

For example, you may narrow down the scope to write about "How windowing works in stream processing?" rather than trying to cover the whole stream processing domain.

The bottom line is to go with content closer to your heart as it gets your creative juice flowing. Even though the scope is small, you can give it your best.

Do your research. Be genuine about your writing

Technical writing should always accompany facts to back it up. A tutorial must provide working code samples to its readers; an explainer post must have diagrams and illustrations; a thought leadership article should contain metrics and data to back up your opinion.

Coming up with the above is called your research, and it can take time. You must at least try out the stuff before you write. For example, if you are writing a tutorial about connecting a PHP application to MySQL, you should build it first. Then only you understand the pain points and the places where readers pay the most attention. 

You should collect all the sources you will refer to for thought leadership content at the end. Also, prepare tables and figures that can be used for comparison. 

All this research yields some time and effort from your end. That is called being genuine to your readers because there's no fiction or mere opinions in the technical writing space.

Structure your content before writing a single word

I made a mistake initially; that is, I sat down in front of my laptop, fired up the text editor, and started writing without any planning.

Soon I realized that my content wasn't good enough to deliver its intended objective. Oftentimes, I was beating around the bush rather than being succinct and to the point.

My friend Shiro helped me out with a method to structure the content in your mind before translating them into words. The idea is to break down your content into sections that would make the most impact on readers. Each section translates into a subheading. When you get that figured out, do the same for each subheading, break it down to further sections.

Rinse and repeat this until you are satisfied with the structure of your content. Finally, start adding words under each section.

For example, the following is how I structure an article about "An introduction to Big Data."

That approach helps you stay in focus while writing. You will not forget what you intended to deliver at the end. Also, you will have a sense of completion as you progress through each section/subheading. I don't usually complete the whole article in one go. Instead, work on different segments each day based on the energy levels I allocate. 

I will talk about that in a future post.

Where to next?

Well, I guess you've learned something about content planning in this post. I will continue this series to talk about the delivery and the post-delivery stages in the coming posts.

I'd like to know your feedback as we progress through the series, whether you agree or have different views that add more value here—comment below or tweet to me to keep our conversation moving.