Technical Writing - The Process¶
Some think writing requires inspiration, a muse, or special talent. While these may (or not) be necessary for writing a fiction masterpiece, they certainly aren't needed to write a decent technical piece. Technical writing is a skill that can be learned and perfected with practice, and there are methods to help you move forward.
The main blockers I've struggled with during technical writing are:
- Lack of original ideas.
- Missing a clear and unified structure.
- Running out of ideas or motivation halfway through.
- Dull and boring writing, lacking impact.
A key ingredient to overcoming these blockers is to iterate a lot. It is impossible for most of us to come up with original, coherent, and impactful ideas, all at once. Instead, you start with a bunch of unconnected ideas, and you relentlessly edit, rewrite, and improve.
The other ingredient is to know when to stop. No technical article is ever ready, you just decide to publish it when it's good enough.
There are two reasons why this relentless editing is difficult:
It is very hard to edit your own words once you get too attached to them. The longer you spend thinking about a specific sentence, the harder it will be for you to let it go.
Besides, language is contextual, every sentence is connected with its surroundings. The longer a sentence lives, there harder it is to refactor it without compromising the story in which it is embedded.
Hence, we need to delay the moment when ideas grow roots to as late as possible. We want them to float freely and bounce around as long as possible. And we want them to grow roots and entrench themselves into a coherent narrative at just the right time.
Here's a losely-defined process that works for me.
It starts with brain-dumping the key ideas before threading an underlying structure. Then, we'll make three passes, one to fill with content, another to prune for clarity and a third one to polish for impact.
And that's it, three drafts and we're ready to publish.
Brain-dump key ideas¶
The first step is to come up with as many ideas as possible, regardless of their quality. You've been thinking about a topic for a while, and you already have a bunch of unconnected thoughts you want to explore. Sit down and write them, one by one, as they come up to your mind.
Forget about structure, order, story, coherence; nothing matters beyond individual ideas. Sometimes an idea requires one sentence, sometimes a couple, and sometimes barely a phrase. Let each idea float freely, unconnected with the rest. Describe it with just the few words you need to understand it when you come back later. It doesn't need to make sense to anyone but you.
The key insight is to not spend too much time thinking about any particular idea. Do not refine them, do not rewrite them to make them clearer beyond their initial conception. Open your mind and let ideas pour out as unchallenged as you can possibly do.
Thread a structure¶
Now you have a heap of ideas, some potentially good, some definitely bad, some ugly. They are floating freely, unconnected, unperturbed by their companions. Most of these ideas won't see the light of day, but you still don't know which ones will make the cut. The next step is to thread a meaningful structure around the ones that really matter.
Your task is to reorder ideas so that similar topics start to cluster and a structure begins to emerge. Since ideas are slim and free, you can move them around, group them into sections and subsections as you wish. Play around with different structures here and there; maybe save copies to revisit later.
Resist explaining or refining the ideas. Keep them slim. Remember that fat ideas grow roots. They become heavy and hard to reorder into a different structure. They attach to their context.
As you play with different structures, you will converge into a definite form, a story where some ideas fit neatly, and some don't. Cut these loose without a second thought. Ideas are cheap anyway. That's why we want them to be slim in the first place, and why we didn't let ourselves get attached to them.
At the end of this step you'll have a blueprint, a kind of skeleton that threads across all the remaining ideas, connecting them into a larger narrative. You'll have removed any idea that didn't fit, and possibly sprinkled here and there a few supporting ones where the structure felt less solid. They are ready to grow roots.
Fill with content¶
Now that you have a solid structure, it's time to let ideas flourish. Expand every idea into a paragraph, or two, or three, as long as you need. You're only interested in quantity now, not quality.
Try and respect the structure you already have in place. Why? Because if you deviate too much from it, you'll be back at square one, lacking a clear structure, but with bloated paragraphs instead of slim ideas. And we already know this is bad: ideas are easy to move around, but paragraphs grow roots, and they are almost impossible to refactor once they start taking shape.
Spend as little time as possible thinking about any given sentence. Just write them down as they come, without concern for clarity, conciseness, or impact. Why? Because the longer you linger on a sentence, the more you'll grow attached to it, and the harder it will be to cut it down later.
Keep adding content as long as you have the energy to do it. At some point, ideas just stop growing, and the struggle to extract meaning from them becomes so big that you spend more time thinking than writing. Stop there. Resist any urge to double-think about what to write. If it's not coming easily, it's time to rest. You might need a couple more rounds to cover all the ideas in your outline, so take your time to recharge.
Prune for clarity¶
At this point you are saying everything you want to say, but cluttered and densely. Most ideas deas are overexposed, overgrown, touching their surroundings too much. You'll have repeated the same stuff over and over. It's time to prune.
Aim to cut every paragraph down to half its size. First, just remove it to see if you needed it. If you don't miss it, it's gone for good. Otherwise, put it back and do the same with every sentence. You'll find that half your content can be cut clean.
Now go over what's left and rewrite to make every idea as clear-cut as possible. Remove everything nonesential. Simplify tenses. Put the action at the forefront of each sentence and paragraph.
Stop when you feel there's nothing unnecesary left. Every word must have a job: if you remove it, something breaks. You can come back a couple times and remove a word here and there. You'll know when it's time to move on.
Polish for impact¶
You have a lean story now, nothing unnecessary, but it's probably kind of gray, dull, boring; using words like "probably" and "kind of". It's time to make it blossom.
In each paragraph, think how do you want the reader to feel: informed, impressed, intrigued, excited? Look for the words that conflict with that desired tone.
Identify the key ideas in your narrative that should feel like a punch in the face. Build momemtum towards them, lowering the tone of the previous paragraphs to make them smoother, and then deliver that punch with maximum impact.
Rewrite those key sentences to make them more impactful, ressonant, bolder. Drop boring qualifiers: instead of "very important" say "crucial". Remove any brakes and cushions.
Finally, find the most relevant idea you want to deliver. Go back and add hints here and there to build towards it: drop an open question early on, or a subtle mention in a related passage. Repeat it a few times to make it ressonate.
And that's it. When you're done with this third draft, your text is ready to publish. Put it out there and move on to the next piece.
I purposefully left out anything concerning getting feedback, and not because it's irrelevant. On the contrary, getting feedback early on is critical. But this is a sufficiently complex topic on its own, so I'll leave it for another ocasion.