What I think about when I edit — Eva Parish
I wrote the main points from this article on an index card that is always visible on my desk. It reminds me to go through the main steps before publishing a blog post. It has made my writing much much better.
Decide what you’re actually saying
I recommend writing a preamble, just for your own use, on everything you write. Take a few minutes and consider what you’re trying to say. What is your main point? Who are you writing for? Then actually write this information down at the top of your document (or notebook, or cafe napkin) so it’s there staring you in the face as you work. As you write, and as you edit, you can compare what you have on the page to what you set out to do.
Repeat yourself (within reason)
This principle applies across most genres. In documentation, a good tutorial will have a brief introduction to what you’re going to do, then the actual procedure, and finally a way for you to verify that you’ve done the thing correctly. In a blog post, you should introduce what you’re going to discuss in the post, then actually do that, and have a short summary at the end. And so on.
These two first tips have really helped me clarify my writing: the right audience, the right message and the right structure take you a long way.
Simplify
Unless you have a very specific reason not to, strive to get to the point as quickly as possible. Don’t bury your meaning in excess words and flowery constructions.
I grew up reading Tolkien and became a big fan of vibrant and colourful language and branching storytelling and for better or worse, I try to balance that with being concise and to the point.
“You should”/“You can”
When writing instructions, anywhere you say “You should X” or “You can X,” replace it with the imperative mood of the verb.
Example: You should save the file to your home directory. Revision: Save the file to your home directory.
This change eliminates a couple words, making the sentence easier to read, and brings the reader straight to the point.
I still struggle with this one as this kind of text is so natural to me.
“Of” and “for” clauses
Instead of using constructions with “of” or “for,” rewrite the sentence to put more information before the noun. This ordering makes the sentence more efficient.
Split it up
Break up long sentences into multiple shorter sentences.
Another piece of my writing that requires the most work. I try to return to my sentences and split them up as I write them. Often I still struggle (originally this sentence was part of the previous!) because I write as I think.
Eliminate passive voice
Passive voice obscures who or what is performing the action. Rewriting a passive construction to be active almost always makes what you’re saying clearer and makes the sentence easier to read, because your reader can attribute the action to the right person or thing.
It may even help you understand what you’re saying better. If you’re describing a system you built, and you say “An alert is triggered and the job is started”—do you know how those things happen? Which service triggers the alert? Which component is responsible for executing the job? In rewriting, you may realize that something doesn’t work as you expected, or that you don’t know how it works.
Don’t use adverbs
You can almost always replace an adverb with a better, more specific verb, or describe what you mean instead. Being more specific is especially key in fiction, but I believe in stripping out adverbs in all types of writing.
Don’t assume knowledge
It’s easy to fall into this trap when you’re writing about something you know well: you forget to consider what you know that your audience doesn’t. You don’t take a step back and provide relevant context. Imagine how much more pleasant it would be to read emails, documentation, etc., if people actually spelled out those TLAs (three-letter acronyms)!
- Spell out acronyms on first use.
- Add a phrase or a sentence briefly explaining a concept when you introduce it.
- Link out to further reading.
When I organised Rails Girls workshops, one piece of advice stuck with me forever. It went something along the lines of “Assume no knowledge but infinite wisdom”. The idea was to treat the workshop participants as intelligent humans who can figure stuff out but don’t expect any specific programming knowledge.
Be aware of your tone
Know what kind of tone you’re going for, and be consistent. You can be colloquial or formal, but not both.
Consistency is my weak point. I even mix up tenses and perspectives because I don’t always remember what I chose when I started writing.
Avoid jargon and cliches
In the business world, jargon means things like “deep dive“ and “low-hanging fruit”. Elsewhere, we love to use cliches. Especially baseball metaphors, for some reason: “step up to the plate,” “hit it out of the park,” “take a swing at it.”
As a non-native English writer I use idioms a lot but at least they are often not business jargon.
Make use of whitespace
Whitespace is key for technical documentation but can also be used to great effect in blog posts, emails, and elsewhere. It’s hard for people to read long paragraphs, especially on a computer screen. They will zone out. Ensure that readers stay with you by visually breaking up the page and making your key points easy to identify.
This. So much this. I consider myself rather good with it. Whenever I see a long wall of text, I either go away or make adjustments myself before reading it.