How to Write Technical Articles

A general workflow for writing short technical documents (essays, blog posts, papers) while meeting your deadlines and staying sane.

Technical writing is one of the most useful skills you can develop. It is the sort of writing that is meant to inform, explain, or discuss a concrete, technical topic in a given domain of expertise. Technical writing is factual, logical, and often backed by evidence. It is also terse and devoid of unnecessary adornments, but it doesn’t need to be dead boring.

The main purpose of technical writing is to produce in the reader a new level of understanding —as opposed to, say, creative writing, whose main purpose might be to entertain or inspire, or political writing, whose main purpose might be to make the reader sympathetic to some cause. Almost everything you read in this blog, including this post, is an example of technical writing.

Since technical writing is about understanding, the process of writing should focus on truthfulness and clarity, while being inspiring and engaging. In this post, I’ll show you a loosely defined process that I follow to achieve those objectives in my writing, which I find makes it easier to write often.

Victorian library interior — lexica.art

The gist of the process is to disentangle content from style. Here’s a TL;DR of the whole process:

1. Brainstorm the main ideas to talk about. These are short, unstructured blurbs of text that encode the main takeaways you think the reader must understand to completely get your message.

2. Define the main talking points, claims, arguments, and evidence for each of those ideas. These might include factual information, data, anecdotes, or well-crafted arguments.

3. Structure the content by reordering the ideas, taking points, evidence, and arguments, in a logical way. This includes adding sections and subsections to bring structure to the article.

4. Draft the first version of your article by expanding talking points into full-blown paragraphs, connecting the ideas. At this point, quantity beats quality.

5. Simplify that first draft by removing all unnecessary boilerplate and repetition and rewriting the text to make it simpler. You should aim to cut between 1/3 and 1/2 of the content.

6. Polish the style of that second draft by changing bland and dull phrases with crisp and engaging writing.

And that’s it. Once you’re done with step 6, you’re ready to publish.

In the rest of this post, I will motivate why this process is useful, then I will detail each of these steps, and finally, I will give you some concrete advice on improving the quality of the content, the clarity, and the style of your writing.

---

Why technical writing is different

Technical writing is a form of communication used to explain complex topics clearly and concisely. As in any form of writing, there are basic linguistic and stylistic considerations that you should follow, the most important being clearly defining your target audience. Only once you know who you’re writing for you can decide the tone, style, and depth of your content.

However, there is one way in which technical writing is special. As I said in the introduction, the purpose of technical writing is to produce a form of understanding in the reader. This means there is something you know, and you want to transport that knowledge into your reader’s mind. The problem is the things that you know are not separated in your brain inside a single file that can download. No, they are interconnected with everything you know.

Thus, technical writing involves this process of taking an amorphous web of interconnected ideas inside your brain and transforming it into a neat package that can be delivered with laser precision to your reader’s mind, so that it becomes an amorphous web of ideas interconnected inside their brain. Like a pill, technical writing consists of a core set of clearly defined ideas wrapped in a nicely digestible envelope.

Types of technical writing

Technical writing encompasses three main types: informative, didactic, and argumentative. Informative writing focuses on providing factual information on a given topic. Didactic writing is more focused and instructional, usually providing instructions or describing the process to do something. Argumentative writing is slightly different in that it uses facts and evidence to make a case to try and convince readers of a particular opinion.

Depending on the type of article you’re planning, some details of the writing process will change, but the general workflow I explain in this post works for any type of technical article.

Informative articles are designed to impart factual information without any bias from the author, allowing readers to form their own opinions. This type of article covers a variety of topics, from news stories and current events to historical accounts. By presenting facts in an unbiased fashion, these articles help readers to make informed decisions and develop their perspectives.

Didactic articles are designed to make readers learn something new. These articles can cover a wide range of topics, from deeply technical algorithms to broader technologies. The key characteristic of a didactic article is its ability to present complex information in an organized, effective way. This often involves providing examples and visualizations to help the reader understand the material, as well as utilizing analogies and intuitive explanations to make the material more accessible.

Argumentative articles are the most opinionated and persuasive pieces of writing; they are designed to convince readers of a certain point of view and to argue in favor of a specific opinion or against another opinion. To achieve this, argumentative articles are usually written as essays that contain logical arguments that are presented in a way that is easy to understand. The arguments must have a clear structure, each step building upon the previous one to establish a solid foundation.

Choosing what to write about

All writing starts with choosing a topic. In the case of technical writing, that topic is always something that you understand better than your reader. But it doesn’t necessarily need to be a topic you’re an expert on. It can be something you just learned or something you’re working on.

An idea for finding a technical topic you feel comfortable writing about is visualizing your reader as the person you were one or two years ago. Find a topic that you can explain to a one-year-ago version of yourself that would make them understand it faster or easier than what it cost you. In my case, I often write with my undergrad students in mind. I choose topics I think I would be interested in reading about when I was a student. You can also do market research: find what your readers are consuming online, make polls, or ask a few of them directly.

The act of choosing a topic is an exercise in defining your audience. You always write for somebody, so the better you can profile that person the easier it will be to find an interesting topic to tell them about. When you do that, should be able to write a single sentence that conveys your primary objective with this piece of writing. In the case of this post, it would be something like this:

Help beginner technical writers improve their process with a workflow to go from a loosely defined idea to a polished article that is coherent and interesting, in a timely fashion.

The workflow

The workflow I will describe in this post is based on the premise of distilling what you know down to its core meaning and packaging it in an optimally digestible way. To achieve that, the key principle is to disentangle content from style.

First, you will define exactly what you want to say, and in which order, devoid of any stylistic considerations. That is the core. And then you’re going to massage it, enrich it, polish it, growing an envelope that makes it easy to digest.

Let’s go.

Step 1: Brainstorm

Begin with an abstract objective for your article and a clearly defined audience. The first step is to expand that abstract idea into concrete talking points: the core ideas that you think are necessary to understand the topic.

For now, all you want to produce is a set of short sentences for each core talking point. You don’t want to focus on anything related to the style of the writing, just on getting all the ideas that could be relevant. Do not bother about order or structure, there is time for that later.

Keep in mind that these are claims, not merely objectives. Most people approach this stage of writing by listing questions they want to answer, like “Explain why technical writing matters”. The problem with this approach is that you’re just delaying the actual task, which is getting those answers out of your brain. Instead, you should write your claims as explicit answers to those questions: “Technical writing is useful for understanding a topic better because it forces you to find sound arguments”.

You can start by listing questions, but then you have to answer them. I've found that starting with some loose questions helps mostly when I'm writing a didactic or informative piece. However, when I'm writing the more opinionated kind of essays, I often already have in my mind some concrete claims that I want to inject into the reader.

The best technique I have found for producing a strong core set of ideas is the reverse outline. This works by starting from an unstructured, raw dump of your mind, and distilling it down to concrete talking points or claims. You can do this by just letting your mind run free and writing everything that comes to you about that topic. But I’ve found it’s much easier for me to talk than write, so I’ll record myself talking for 10-20 minutes on a particular topic, speaking my thoughts aloud without worrying about order or structure. It works best if I take a walk and use a recorder app on my phone. After I record the audio, I will transcribe it and go over each paragraph to distill it down to its main idea.

At the end of this step, you should have a comprehensive list of relevant ideas from which you will extract your core claims. This is all you could talk about.

Step 2: Define

Having a comprehensive list of talking points and claims is a good starting step. Now you need to narrow down and refine those claims into well-constructed, precise statements that are backed up with evidence, arguments, and counterarguments, including providing data to support the claims or citing credible sources.

First, you have to cluster and deduplicate the claims, creating a cohesive set of core ideas that are not vague or repetitive. This helps to narrow down your focus to the most important ideas and allows you to present them concisely and compellingly.

Since technical writing is factual, you need to support the claims made throughout the document with evidence and well-crafted arguments. Go over each of your core claims and decide which of them needs further support. This support can come in the form of evidence such as links to reliable sources, citations of experts in the field, or further arguments that bolster the claim. This can be the most time-taking step, especially if you’re writing about a historical or current event.

The type of support for your claims in an article will vary depending on the type of article you are writing. For example, an informative post about a recent news story requires citations, while a didactic post, such as a tutorial on a technique, could be refined with explanatory examples. On the other hand, an argumentative post can be reinforced through logically sound arguments.

At this step, you may decide that some of your core claims are unnecessary or insufficiently understood, and you may change or remove some of them until you are satisfied that everything is well supported. You will also find counterarguments or contradictory evidence for some of your claims, and you will need to decide whether to remove them or to keep them taking into account the new information. These are just two examples of ways in which you will probably deviate from this process, and go back to previous steps.

If your audience is knowledgeable on the topic you are writing about, then the arguments you use should respect their level of understanding. On the other hand, if your audience is unfamiliar with the topic, you should use simpler arguments that are easier for them to understand. In either case, don’t be condescending, explain things as simply as necessary, but don’t oversimplify ideas to the point they become inaccurate.

At the end of this step, you should have a small, cohesive set of core ideas, precisely defined and well-supported, that together will form the core of your article. This is what you want to talk about.

Step 3: Structure

Up to this point, all you have are a set of more-or-less independent claims with all their support. Once the main claims and arguments are in place, it’s time to give some structure to the whole piece. It is only now that you will consider sections, subsections, and paragraphs.

Depending on what you want your reader to focus on, you will order the ideas differently. For example, if it’s a didactic piece, then you will probably want to begin with intuitions that help the reader understand the why before the how. If it’s a more informative piece (e.g., a historical account or a summary of recent events) then you’ll probably want some sort of chronological order. If it’s an argumentative piece, you’ll want to sort the claims so each one is supported by previous claims.

At this point, you may find that some of your claims are not sufficiently developed, or that you’re missing a link somewhere. This might prompt you to go back to steps 1 and 2 to refine your claims. These first three steps can thus be somewhat cyclic. You can brainstorm, define, and structure, just to notice that you missed some key ideas, and then brainstorm, define, and restructure again. Just don’t overdo it.

At the end of this step, you should have a clear picture of the final document layout, the sections, subsections, and the core claims and their supporting arguments in their optimal order.

Step 4: Draft

At this stage, the ideas have all been incorporated into an organized structure that effectively conveys a message. Now, each claim, argument, or point must be fully fleshed out into a comprehensive paragraph. This means elaborating on the points with examples, explanations, and additional ideas, and ensuring the sentences and ideas flow together cohesively. The audience plays a crucial role here. How much they know about the subject will influence how deeply you dive.

Just write. Prioritize quantity over quality.

When it comes to writing, don't become too fixated on adhering to one particular style. Instead, focus on developing your ideas and getting them across. Don't be afraid of using phrases that seem superfluous, as they can often help keep the writing flowing. Don't worry about how the sentences and paragraphs are laid out; you can always go back and refine them later. Don’t worry about verbosity and repetition either, you will come back, tweak, and polish your writing until it is exactly as you want it.

Reusing content from step one of the process can be a useful way to quickly fill up space, but oftentimes the structure you come up with is so different that it makes more sense to start the process again. One possible way to do this is to record yourself speaking and then simply write down everything you said. You could use an automatic transcription tool to do it more quickly.

At the end of this step, you should have roughly 1.5x the amount of content you need, and be satisfied that everything that could be said is in there.

Step 5: Simplify

At this point, you have a first draft with more than enough content. Now it’s time to make it clear. This will be a major edit, cutting down between 1/3 and 1/2 of the word count while improving the quality. If you want to finish somewhere below, say, 2k words then you should begin with 3k or more.

The purpose is to say the same things with the minimum amount of words. Rewrite sentences to keep their gist while removing all unnecessary words. If you manage that, your writing will be crisp and clear. Keep an eye out for throwaway phrases, things like “in order to”, “with the purpose of”, or even full sentences that don’t provide anything new. Cut them shamelessly, they always make your writing more boring.

When in doubt, cut.

Once your sentences are short, clear, and crisp, you can move one level up to paragraphs. Try to make each paragraph begin with a claim or talking point, and continue with supporting arguments. The final sentence of a paragraph can either be a leading sentence, that connects with the next paragraph, or a surprising conclusion that adds a new insight. Avoid ending with a summary sentence unless that summary brings some new understanding.

The best way to spot overly complex wording is to simply read your text out loud. If you stumble on a phrase or find yourself struggling to get the words out, that’s an indication that the phrase is too long or complicated. If you sound dull and monotonous, with all sentences the same length, then your text will be boring to read. You should write as you speak. If it sounds like something you wouldn’t say in conversation, you’ll know it’s time to tweak the wording.

At the end of this step, your article should be well structured, backed by solid arguments, and easy to read from top to bottom. You could end here, but we’ll make one final pass to polish it.

Step 6: Polish

As a final step, you’re now ready to tackle the style. Ask yourself again about the intended audience, are they technically savvy, or are you aiming for a general audience? Are they fine with technical lingo? Ask yourself also about the tone you want. Is it a sober and informative piece, an engaging and optimistic take, a warming invitation to explore a new topic, or a kind of warning?

Consider the feelings you want the reader to experience. Examine the text and make subtle changes where necessary. For instance, replace uninteresting words with captivating synonyms that better transmit the desired emotions. This will help engage the reader and make the text more powerful and evocative. The key is to be mindful of the desired impact and incorporate words that will effectively communicate the intended message. With a little extra effort, the text can be transformed from lackluster to influential, thus ensuring it resonates with the reader.

In contrast with the previous edit, this should not be a wholesale overhaul, but rather a careful refinement of the text, seeking out those few words that will truly bring the desired tone and atmosphere to life. Minor edits can make a huge impact, and when done correctly can even change the entire meaning of a sentence.

And then you publish.

Don’t spend any extra amount of time doing a second round of editing. Perfection is the enemy of high quality.

---

Final considerations

When I wrote this post, I went into it with a good sense of the structure I wanted it to follow. Thus, I wrote the introduction almost entirely before moving on to the other sections. I added the first three sections when the rest was almost ready because I felt there was a need for some introduction. But I still made sure to continually iterate on the ideas and arguments within each part of the document and I strived to ensure that each one was clear and concise and that I was expressing my thoughts in the most effective way possible.

After step 4, probably not all parts of the article will evolve at the same time. You might have sections that grow faster and arrive at style check while others are still barebone bullet points. That’s fine, too.

This workflow can help you write better, avoid writer’s block, and make a pleasure out of writing. But the end goal is getting the article out there, not getting the process right. Anything that gets in the way of writing is an obstacle, so feel free to deviate as you need. It's okay to adjust it to fit your writing style or any specific needs you may have. Try to be flexible and have an open mind when approaching your writing workflow, as this will help you to create a positive experience.

Asking for feedback

You can ask for feedback at any step of the process, as long as you ask for the exact kind of feedback that is useful.

See, many readers won’t be able to disentangle content from style, at least on a first read, so if you ask them for feedback on the initial unstructured list of claims, they will probably flood you with useless —at this point— suggestions about word choice, grammar, and sentence structure.

The solution to this is two-fold.

First, ask for specific feedback. Instead of “What do you think about this?”, ask specifically about the step you’re in. “Hey, I’m writing a piece on X, here are the main talking points I plan to cover… Do you see anything missing?”. Or, when you’re at step 4, you can ask something like “What is the most boring 20%? What is the 10% that I must keep?”.

The second way is to be selective about who you ask. Some people are better at analyzing factual content and others will be better at proofreading or style check. Don’t ask the same feedback from the same 100 people, since you won’t be able to read it anyway.

And finally, understand that all feedback is optional, and only you know what message you want to get across. Yes, you should pay attention to your readers’ suggestions, because they are the ones you write for. But, if a piece of concrete advice goes against your gut feeling, trust your instincts.

A note on writing tools

You may have noticed there’s nothing in this guide about how to implement something like this workflow. It is purely conceptual. You could do it with pen and paper, a traditional word processor, a specialized writing app, or using an AI-powered writing assistant. That being said, some parts of this process can be aided with the right tools.

A good text editor will let you move entire blocks of text easily, navigate back and forth between sections without having to scroll with your mouse, fold and hide pieces of text when necessary, check grammar and orthography, and add comments that won’t be shown in the final version to guide yourself. All of that will help you a lot.

Likewise, there’s a lot you can speed up by talking and transcribing instead of directly writing. You can transcribe manually, but there are plenty of good enough automatic solutions out there, some even free.

Regarding generative AI tools, there are some controversies but I think you can make good use of them without losing your voice or being disingenuous. This very article has seen maybe 30% of its content go through AI writing tools, but I’ve reviewed every single word and tweaked almost every sentence afterward. I use them to rewrite sentences more clearly, expand on some talking points, suggest claims or ideas similar to the ones I already have, transcribe my audio recordings, extract key claims from longer paragraphs, etc. As long as you are conscious of the process, and you stand by the final text, I would call that a fair use.

Recap

Here’s a quick recap of the whole workflow. You start with a nebulous idea in your head, that you need to distill down into concrete talking points. Then you will review, refine, and support those talking points with evidence, arguments, and citations until you’re satisfied they stand on their own. Next, you will sort and cluster them to thread an outline that connects all the dots and fills in the gaps. Then you write, as much as you can, without worrying about quality. This is your first draft. You wrap up by making exactly two passes: a long and careful edit to simplify the text as much as possible, and then a quick polish pass to tweak here and there and find the exact tone you want.

The main takeaway of this article is to separate content from style as much as you can. Decide what you want to say first, and then how you want to say it. That’s the key to high-quality and scalable technical writing. The rest is up to you, go find your voice and rhythm.