A Pragmatic Workflow for Technical Writing

Introducing the CODER Framework, my home-made workflow.

No actual LEGO toys were harmed to produce this image.

Technical writing is one of the most valuable skills you can develop. It is the sort of writing 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, writing should focus on truthfulness and clarity, while being inspiring and engaging. In this post, I’ll show you a loosely defined process I follow to achieve those objectives, making it easier to write often.

This article is an updated and improved version of an old article I published in

The Tech Writers Stack

when I was just getting started with technical writing. This new version incorporates the experience of more than 100 articles written and published since, which have garnered more than 50 thousand views in total.

A Framework for Technical Writing

In this article, I will outline the CODER framework for technical writing: a structured approach to writing that I’ve converged on, designed to ensure clarity, coherence, and quality. Each step builds upon the previous one, guiding authors from idea collection to final publication.

The core of this process consists of five steps:

1. Collect: Gather all ideas, thoughts, talking points, arguments, evidence, etc.

2. Outline: Organize those ideas and create a structured outline of the document.

3. Draft: Write, expanding on all the ideas and filling in any gaps.

4. Edit: Improve the structure, content, and style of the document.

5. Release: Finalize the article, including formatting, adding images, tags, and metadata, and preparing it for publication or distribution.

In the rest of this post, I will explain 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 that explains 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 can you decide your content's tone, style, and depth.

However, there is one way in which technical writing is special. As I said in the introduction, technical writing aims 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 that the things you know are not separated in your brain, and they are inside a single file that can be downloaded. No, they are interconnected with everything you know.

Thus, technical writing involves 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 to become 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 step-by-step guidance or describing the process of doing something. Argumentative writing is slightly different in that it uses facts and evidence to make a case to try to convince readers of a particular opinion.

Some details of the writing process will change depending on the type of article you’re planning, but the general workflow I explain in this post works for any 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 various 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 help readers learn something new. They 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 containing logical arguments 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 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 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 chose topics I think I would have been interested in reading about as a student. You can also do market research: find what your readers consume 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, you 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 that will quickly transform a loosely defined idea into a polished article that is coherent and interesting.

Dissecting the CODER Framework

The workflow I will describe in this post is based on 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. Then, you’ll massage, enrich, and polish it, growing an envelope that is easy to digest.

Let’s go.

Step 1: Collect

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, you only want to produce 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; you just want to get 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 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 of 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 must answer them. I've found that starting with some loose questions helps mainly when writing a didactic or informative piece. However, when I'm writing more opinionated essays, I often already have some concrete claims that I want to inject into the reader.

The reverse outline is the best technique for producing a solid core set of ideas. This works by distilling your mind from an unstructured, raw dump of 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 it’s much easier 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 central idea.

At the end of this step, you should have a comprehensive list of core ideas, supporting arguments, evidence, etc. This is all you could talk about.

Step 2: Outline

At this point, you have a set of more-or-less independent claims with all their support. Once the central claims and arguments are in place, it’s time to give some structure to the whole piece. Only now will you 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, 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), you’ll probably want 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 missing a link somewhere. This might prompt you to return to step 1 and refine your claims. These first two steps can thus be somewhat cyclic. You can collect and outline, just to notice that you missed some key ideas, and then collect and outline again. Just don’t overdo it.

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

Step 3: Draft

At this stage, the ideas have all been incorporated into an organized structure effectively conveying 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.

Don't become too fixated on adhering to one particular style right now. 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 refine them later. Don’t worry about verbosity and repetition either; you will come back, tweak, and polish your writing until it is exactly what you want.

Reusing content from step one of the process can be a useful way to quickly fill up space, but often, the structure you come up with after step 2 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 simply write down everything you said. You could use an AI transcription tool to do it more quickly.

At the end of this step, you should have roughly one-and-a-half to twice the amount of text you need and be satisfied that everything that could be said is in there.

Step 4: Edit

With your draft in hand, it’s time to roll up your sleeves and dive into the editing process. This stage is where the real magic happens, transforming your rough draft into a polished piece of writing. Editing is not just about correcting mistakes; it's about enhancing clarity, coherence, and overall impact.

Editing works better if you use a top-down approach, focusing first on the central issues with the document structure and high-level ideas and then zeroing down on the specific wording of each phrase.

So start by taking a step back and examining the structure of your article. Does the flow make sense? Are your arguments logically sequenced? You can rearrange paragraphs or sections to create a more compelling narrative. Don't hesitate to cut something out if something feels out of place or redundant. Remember, every paragraph should serve a purpose and contribute to your main message.

Next, zoom in on the details. Read through your draft with a critical eye, focusing on grammar, punctuation, and sentence structure. This is where you can refine your language to ensure it’s precise and engaging. Read your work aloud; this technique can help you catch awkward phrasing and identify areas where the rhythm feels off. If a sentence doesn’t flow smoothly, rework it until it does.

Always consider your audience at this stage. Are you using language that resonates with them? If your readers are novices, avoid jargon or provide clear explanations. If they are experts, ensure your content is rich with insights and depth. Tailoring your writing to your audience’s knowledge level is crucial for effective communication.

Don’t shy away from seeking feedback. Share your draft with trusted colleagues or peers who can offer constructive criticism. Fresh perspectives can highlight strengths and weaknesses you might have missed. Be open to their suggestions, but also trust your instincts about your content.

Finally, take a short break before performing a last read-through. This brief distance can help you spot inconsistencies, typos, or awkward phrases.

By the end of this step, your article should be refined and ready for the next phase. You should feel confident that your message is clear, your arguments are compelling, and your writing is engaging. Editing elevates your work to its highest potential, ensuring it resonates with your audience and effectively communicates your ideas.

Step 5: Release

Now that your article has been meticulously edited and polished, it’s time for the final step. This is where you take all your hard work and prepare it for the world to see. The goal here is to ensure that your content is ready for publication and optimized for maximum impact.

Begin by focusing on formatting. Ensure your article adheres to any specific guidelines or standards required by your publishing platform. Check that your headings, subheadings, and fonts are consistent throughout the document. Proper formatting enhances readability and gives your article a professional appearance.

Next, it’s time to add supplementary elements to enhance your content. This includes images, charts, or infographics that illustrate your points and make the article more engaging. Ensure all visuals are high-quality, properly attributed, and relevant to the content. Don’t forget to include alt text for accessibility and SEO purposes.

SEO is a crucial aspect of this final step. If your platform allows it, add relevant tags and metadata to your article to improve its visibility online. Consider keywords your audience might search for and incorporate them naturally into your content. This will help your article reach a wider audience and drive more traffic to your site.

Before hitting that publish button, take a moment to do a final review of the entire article. Check for any last-minute errors or formatting issues that might have slipped through the cracks. Ensure that all links are functional and that your citations are accurate. Read the article from top to bottom on a different device and screen size to where you wrote it, e.g., on your phone. This will help you more easily catch subtle formatting errors.

Once everything is in order, it’s time to publish your article. Publish it on your chosen platform, whether a blog, a technical journal, or a social media site. Share it with your network and promote it through various channels to maximize its reach.

Finally, take a moment to celebrate your accomplishment! Completing an article is no small feat, and you should be proud of your work. Remember, the Release step is not just about publishing; it’s about sharing your knowledge and insights with others. Your article has the potential to inform, educate, and inspire, so embrace the opportunity to make an impact.

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 an introduction was needed. However, I still made sure to continually iterate on the ideas and arguments within each part of the document. I strived to ensure that each one was clear and concise and that I was expressing my thoughts most effectively.

After step 3, probably not all sections will evolve simultaneously. 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 the process right. Anything that gets in the way of writing is an obstacle, so feel free to deviate. It's okay to adjust it to fit your writing style or any specific needs. 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 useful feedback, although most people are only comfortable asking for feedback after the first round of edits.

In part, writers do this because 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 your step. “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 in edit mode, you can ask, “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 are better at proofreading or style checking. Don’t ask for 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 convey. You should pay attention to your readers’ suggestions because they are what you write for but, if 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 an AI-powered writing assistant. That 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 quickly, 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, you can speed up a lot by talking and transcribing instead of directly writing. You can transcribe manually, but there are plenty of good automatic solutions out there, some even free.

Regarding generative AI tools, there are, of course, many takes on what is a genuine and ethical use of them to enhance but not replace your voice. You can use them well without losing your voice or being disingenuous. This article has seen maybe 30% of its content go through AI writing tools in all stages, from idea collection and outlining to the final tweaks, but I’ve reviewed every single word and tweaked almost every sentence afterward.

I use generative AI 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 essential claims from longer paragraphs, etc. As long as you are conscious of the process and 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 that you need to distill into concrete talking points. Then, you will review, refine, and support those talking points with evidence, arguments, and citations until satisfied they stand independently. 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. Now you become your harshest critic and carefully edit your article, but don’t overdo it: often two passes—one for high-level, structural review and one for wording and style—are enough. And finally, you release.

The main takeaway of this article is to separate content from style as much as possible. 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.