# What I Think About When I Edit - Eva Parish Synced: [[2024_04_16]] 1:23 PM Last Highlighted: [[2024_04_15]] Tags: [[Advice]] [[Career Growth]] [[Explainer]] [[Personal Growth]] [[PKM]]  Write what you mean; no more, no less. Summary: This text discusses essential editing principles for improving writing clarity, such as restating key points, simplifying language by removing excess words, and avoiding adverbs. It emphasizes the importance of clearly conveying ideas, breaking up complex sentences, and avoiding assumptions about the reader's knowledge to enhance readability. The author's editing philosophy revolves around saying exactly what you mean without unnecessary words and considering the reader's perspective for effective communication. ## Highlights [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg411yxs7cj2g2j4mjh0vxp) > 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. [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg41cgpjwj38h99m763xfd1) > Even if you think you’ve made your point very clearly, it’s worth restating it at the beginning and end of what you’re writing to make sure the reader gets it. [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg42h5tsgyztfjvhr5xn49h) > 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 [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg441tbs7xpxg2ry6f75920) > Instead of saying “this,” you should spell out exactly what you’re referring to, *even if you’ve just mentioned it*. This duplication can feel repetitive when you’re writing it, but it won’t feel repetitive to your reader—it’ll make your writing clearer and easier to follow. [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg46dssg7pqkw0q0e42pg90) > 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](http://www.cws.illinois.edu/workshop/writers/verbmood/). > > *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. [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg47a0nyws4v7w8sqxwzb8j) > 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. > > *Example:* The manager of the team responsible for marketing > > *Revision:* The marketing team’s manager [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg495qq8m0a44q2880c4m61) > Split it up > Break up long sentences into multiple shorter sentences. > > *Example:* Due to the Acme project which just completed a major milestone of having all non-staging servers running in the Foobaz environment, we now see build times of sub-10 minutes which were previously taking over an hour when running with the XYZ plan. > > *Revision:* The Acme project recently completed a major milestone: all non-staging servers are now running in the Foobaz environment. Builds now take fewer than 10 minutes to complete. This change is a significant improvement, as builds on the XYZ plan previously took over an hour to complete. [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg4a4sd17hj2acfeyqxh4sy) > I’ve noticed a trend towards people dropping commas after subordinate clauses. I always add them back when I edit: > > *Example:* If you’re looking for me I’ll be in my office. > > *Revision:* If you’re looking for me, I’ll be in my office. > > *Example:* Due to the fog our flight was delayed. > > *Revision:* Due to the fog, our flight was delayed. > I suspect that this is because, when we speak colloquially, we don’t pause at that point in the sentence. However, grammatically, [you need a comma after a subordinate (or dependent) clause when it comes at the start of a sentence](https://owl.purdue.edu/owl/general_writing/punctuation/independent_and_dependent_clauses/index.html). Besides being “correct,” the comma helps the reader pause and process what they’ve just read before moving on to the rest of the sentence. Using commas after subordinate clauses improves reader comprehension [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg4cdmd0773n1358jmb02hr) > **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. > > *Example:* The fire alarm was pulled and the building was evacuated. > > *Revision:* The fire marshal pulled the alarm and the employees evacuated the building. > > *Example:* Millions of dollars were embezzled from the company. > > *Revision:* Two executives embezzled millions of dollars from the company. > 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. > In technical documentation, you lose precision when you don’t attribute the action to someone or something. And in all writing, refining your language refines your understanding of the world. [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg4e8d5vv6s270a17cpq6az) > There is nothing *inherently* wrong with adverbs. They are just part of a category of things that I believe are lazy in writing. When I say “He laughed loudly,” I’m relying on my reader somehow intuiting the precise volume of his laughter. “Loudly” could mean a million things, but what I really had in mind is that “He laughed with the kind of booming abandon that made the whole restaurant turn around and look.” > People also often use adverbs as a hedge: “Basically, it's this.” “Essentially, this is what I’m saying.” Is it, or isn’t it? Remove the adverb and commit to saying whatever you’re saying. [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg4kvek4wgbhw672adctqhv) > Let’s start with an example, and look at a few ways we can improve it. > > *Example:* This chart shows the TTFB for our website over the past week. > To some people, this sentence makes perfect sense. To many people… not so much. > • *Spell out acronyms on first use.* Any time you introduce an acronym or an initialism in a document, spell out what it means and put the acronym in parentheses. Thereafter, you can use the acronym by itself. > > *Revision 1:* This chart shows the time to first byte (TTFB) metric for our website over the past week. > You might think it’s obvious what an acronym means, but a new reader may not. > • *Add a phrase or a sentence briefly explaining a concept when you introduce it.* > > *Revision 2:* This chart shows the time to first byte (TTFB) metric for our website over the past week. TTFB measures how long it takes from when a user makes an HTTP request to when the user’s browser loads the first byte of data. It’s used as an indicator of how responsive a website is. > • *Link out to further reading.* Once you define a concept and the corresponding acronym, provide a link to somewhere that the reader can learn more about that concept if they’re still curious. You don’t have to call attention to the link. > > *Revision 3:* This chart shows the [time to first byte (TTFB) metric](https://en.wikipedia.org/wiki/Time_to_first_byte) for our website over the past week. TTFB measures how long it takes from when a user makes an HTTP request to when the user’s browser loads the first byte of data. It’s used as an indicator of how responsive a website is. > By now, your readers are with you, and they’re ready to proceed, feeling confident that they have an idea of what you’re talking about. [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg4qt7n0tg1th5gz2k1asgt) > In the business world, [jargon](https://www.grantthornton.com/-/media/content-page-files/press-releases/2018/Jargon-Index-2018.ashx?la=en) 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.” > It will always be better and clearer when you say exactly what you mean. **Using jargon is lazy, and it assumes that the reader is part of the in-group that uses that jargon** (see also: Don’t assume knowledge, above). It can be difficult for non-native English speakers (or non-Americans, when it comes to baseball) to follow your writing when you use jargon and cliches. > > *Example:* tl;dr, if you can hack something together by EOD, that would be great. > > *Revision:* Can you deliver a prototype by the end of today? > The original sentence has incomprehensible acronyms and tech slang, and doesn’t even sound like a request. The second one is straightforward, and asks for what the writer needs and by when. [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg4t8jeps8cr35tktg8g3bb) > 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. > A few suggestions: > • Break up long paragraphs into multiple shorter ones. > • Use useful **subheadings** to give your document some structure and allow readers to skip ahead to the section they’re interested in. > • Use **lists** where relevant, because it’s easier to read a bulleted list of items than to read a paragraph with the same information. > • When you need to convey large amounts of information (for example, in reference documentation), **tables** are even better than lists. > • Use **bold** so that readers who skim (i.e., everyone) will still pick out your main points. (For an example, see the body of this post.) [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg4tnqv7sp589mm7j991trd) > To simplify what you’ve just read, my editing philosophy can be reduced to two tenets: > • *Say exactly what you mean*, which means not relying on adverbs, jargon, cliches, or hedges, and > • *Take out all unnecessary words* [[2024_04_15]] [View Highlight](https://read.readwise.io/read/01hvg4vahysx841stxdky20e1t) > **The point of editing is to think about how you’re using language and to make choices that suit the message you want to deliver**, *not* to unquestioningly follow rules—mine or anyone else’s.