Zen and the Art of Revising Technical Articles

A principled approach to revising technical articles that doesn't suck your soul

Mastering the art of revising technical documents can be challenging, as most writers dread the revision phase. It's thrilling to let your thoughts flow onto paper, but revisiting your work to correct inconsistencies and errors can feel like a chore rather than a creative exercise.

Many technical writers struggle with revisions for two main reasons. First, it's difficult to balance generating new ideas while simultaneously critiquing your writing. Second, many writers revise their work in an unstructured and unfocused manner, often by simply rereading and making changes until nothing else seems wrong. This approach is far from ideal.

In this article, I'll introduce a more effective revision method that works for me and many successful writers across various genres. Adapted from prolific fantasy author Brandon Sanderson, this technique is applicable to fiction, technical documents, and textbooks alike.

The method revolves around two key principles: decoupling writing from revision and revising with intention.

---

---

Principles of effective revisions

By separating the writing and revision processes, you can enter distinct mindsets for each task. This allows you to focus on creativity while writing and critical analysis during the revision phase. When revising with intention, you avoid simply correcting errors as you encounter them. Instead, develop a structured plan that addresses specific issues in your document. Following these principles can help transform the revision process into a more enjoyable and efficient experience for any writer.

Decouple writing from revision

Think of yourself as either the creator or the critic, but not both at the same time.

When in creator mode, focus on writing whatever comes to your mind. Some writers are more structured and prefer a clear outline, while others are less structured and like to let their thoughts flow freely onto the page. Regardless of your approach, when writing, just write. Don't revise or reread what you've written – simply create.

Once you have your first draft, switch to critic mode, but take a break before revising it. It can be a short walk, making coffee, or watching a YouTube video. Or just sleep over it for a couple nights. Give your mind some time to reset from the writing process.

When you’re on critic mode, your goal is to analyze and improve your work. Tackle revisions one step at a time – don't try to fix everything at once. Instead, focus on specific aspects during each revision phase. We will expand on this idea next.

In critic mode, don't make any changes to the document. Instead, go line by line and make comments on sections, highlighting sentences or words that need improvement. There is some nuance here: you can fix minor issues like typos or missing commas –most writing software will catch these errors anyway–, but don’t fix anything that takes, say, more than five seconds of thought. Instead, just leave notes.

After finishing revising the document, take another break to clear your mind. Later, return in creator mode to address the revisions. Although you should focus on fixing the identified problems, don't feel restricted by them. You can disagree with the revision or add new sections inspired by your critique.

Remember to allow yourself creative freedom while addressing the revisions, as this will help improve your writing overall. Perhaps add a dash of excitement and consider differing slightly from the critic's viewpoint. Treat the critic not as a commanding boss, but as a helpful editor offering suggestions to enhance your work.

Now you get the picture, right? Enter creator mode, make adjustments, and then allow your text to rest before revisiting it for further revisions. Continue this back-and-forth until you're pleased with the results. By separating these two roles and being mindful of your objectives during each stage, you'll create a more efficient revision process that allows you to make the most of your writing and editing sessions.

Revise with intentions

Tackle each revision with a concrete plan of what issues to look for.

When revising a document, you may face various issues, from missing commas and weak verbs to unsupported conclusions and major structural problems. Revising with intention means separating your concerns and addressing them from high-level to low-level problems.

First, focus on the document's structure. Is your main claim clear? Do each section and part support that objective? Is the order of arguments and ideas correct? Should anything be explained earlier? Does your conclusion tie everything together, or is it scattered? Is there a strong introduction with a motivating problem or example? Consider the story your writing conveys and assess its coherence, flow, and organization.

Next, address low-level concerns like engagement and clarity. Choose the best words and synonyms to convey your message. Select strong, clear verbs that communicate your intentions effectively. Are you using a passive voice, or is your writing active and engaging?

Mid-level problems involve paragraph structure and clarity. Make sure each paragraph supports your argument effectively and clearly. Can you rearrange the order or words to improve clarity? Consider moving the premise to the beginning and the conclusion to the end.

You can divide the editing process into multiple stages. A simple approach is two stages: one for structure and one for content. For short articles, start by reviewing the overall structure and flow of ideas. Then, thoroughly revise the content to ensure appropriate synonyms, words, verbs, voice, and sentence structure. This is what I do with most of my blog articles.

You can also split it into three phases: 1) high-level story structure, 2) clarity of ideas, and 3) engagement. First address the high-level story, then focus on each argument's explanation and consider adding examples or reordering explanations for better support. Finally, review engagement by examining verb strength, active sentences, and meaningful word choices. This is what I do with longer articles, such as book chapters or scientific papers.

Now, here is the important part. When entering critic mode for revisions, clearly state which phase you're in and focus on detecting specific issues. Before starting the revision process, state your objective and identify the issues you're looking for. Write down general questions that address these problems, such as: Is the structure's order correct? Is the tone active and engaging? Are all verbs strong and meaningful?

As you revise, refer back to these questions and assess the text based on them. When providing criticism, avoid simply saying something is wrong. Instead, explain why it's wrong: The structure isn't right, it's not easily understood, or it doesn't address the claim being made. Be detailed in your critical revision.

However, don't suggest solutions at this stage. Just criticize. Point out if the tone is too casual or formal, if a verb is weak, or if an argument lacks evidence. Leave a focused set of comments for your next creative phase.

Final remarks

Let's end by discussing some caveats to the principles we mentioned earlier. First, the principles themselves are more important than their strict implementation. The key ideas are that you should either be writing or revising, but not both at the same time, and that you should have a clear idea of the issues you're looking for when revising, instead of looking all over the place.

You don't need to be extremely structured with your schedule; some people prefer a looser approach. The important thing is to keep these principles in mind when working on your document.

When revising, take notes and write them down. One common issue with revision is making mental notes of problems and then trying to fix them without writing them down. Instead, put yourself in the shoes of someone who isn't the author and leave thorough notes about the document. Don't overthink these comments – they're for yourself, so focus on addressing one specific issue per note.

Lastly, how long should you revise? Ideally, you would continue until you're satisfied with your work. However, remember that perfection isn't always achievable; focus on creating clear and effective content while adhering to these principles.

For most, the “revise until satisfied" method doesn't work because you'll never be satisfied with your own work. So, what I do is set a fixed number of cycles, like two revisions—one high level and one low level—and then I publish.

Of course, you have some freedom when in creator mode.If you feel the high-level structure is okay during a revision, you can move to the next stage. Alternatively, you may leave a note for your next editing session to do another high-level revision pass. You have the freedom to do this, but working with constraints is important.

Tell yourself you have two or three revisions to fix it, and then hit publish. Otherwise, you may perfect your document forever without ever being satisfied.

---