In this post, I share my notes on doing document revision
As an engineer working in a company with more than 1000 people, I am often in a position to read and write documents. Documents, when used in moderation, can be useful for getting input on a design spec, describing a problem and context, or describing how a project was carried out, e.g. this is how we built our first ever lunch place automatic rotation assignment system to avoid the same debate we have every week.
I reflected a bit on how I tend to revise documents, and I tried to distill into a three key steps to guide my future revision work.
Step I: Grammar
It’s hard for me to just glance over text that has grammatical errors. I make such errors all the time, including in previous posts. So I let myself indulge in the compulsion to correct tiny grammtical problems. The more grammar policing I do first, the less it will distract me later.
Step II: Logical Flow
After reading through the first pass and noting grammatical errors, I do a pass to identify the logical flow of sentences, paragraphs and sections. Is it coherent? Is there a proper beginning, middle and end? In this pass, I once again ignore deeper aspects of the content, focusing essentially on the structure.
Cohesion is a very key aspect of this pass. It’s not uncommon for for multiple people to contribute to a document. Sometimes, what ends up happening is that some sections will be in the formal and others informal. Or some paragraphs will be written is the past tense while others will be in the present tense, while describing the same situation.
I try to weed these issues out and make sure the flow is well aligned and cohesive. And from there, I am ready for the third and final pass.
Step III: Intent & Formatting
In my third and final pass, I will take a step back and try to focus on the intent and formatting aspects of the text. What is the goal of this document? Does its structure help achieve that goal? Maybe there is a whole introduction section that gives very good but irrelevant context to the purpose - and therefore should either be moved to an appendix or just deleted. Maybe the purpose is to compare different options and argue for one approach over another - but the author argues for the preffered option prior to listing out other alternatives – which can be accompanied by biased lenses.
This is, naturally, the hardest part of the review, which is why I leave it for last. Without the distraction of language aspects, I can focus on the ideas and intent of the text, and make formatting suggestions along the way - this should be a heading; or these should be listed as bullet points for clarity.
On some occasions, it may be benefital to separate the intent review from the formatting review. But I often find that formatting can go a long way in influencing the clarity of the intent, which is why I tend to combine them.
And that’s my process. If you have a different one, I’d love to hear about it.