Original source found at:
What I think about when I edit (2019)
11–20 of 138 posts
Re: What I think about when I edit (2019)
#12> You’ve heard this advice before. But you should understand why you shouldn’t use passive voice in your writing. It’s not just “bad style.”
The ususal misunderstanding that everyone repeats.
Read Williams‘, Clarity and Grace, or watch McEnerny‘s lecture on YouTube.
Passive has its use, and it‘s not "to obscure who is doing the bad thing".
Re: What I think about when I edit (2019)
#13Any other engineers trying to improve their writing skills? Any additional resources or tips to help me refine my drafting and editing process?
Strunk & White is always good to thumb through: https://archive.org/details/TheElementsOfStyle4thEdition The Wikipedia has links to other copies, like on Project Gutenberg.
Re: What I think about when I edit (2019)
#14I love this. Inevitably I want to make some improvements. > “He laughed with the kind of booming abandon that made the whole restaurant turn around and look.” The kind of ? If it's a kind that exists generically then we can't have a past tense, so: “He laughed with the kind of booming abandon that *makes* the whole restaurant turn around and look.” But really, why emphasise it being generic? This is better: “He laugh…
If it's a kind that existed generally, then we can have a past tense.
"He laughed with the kind of booming abandon that made the whole restaurant turn around and look, in the before-times."
Re: What I think about when I edit (2019)
#15I was a doc reviewer in my corporate past life and found myself using many of these guidelines. I’d add one more: don’t use different names for the same thing. Many of the docs I reviewed had multiple authors and quite often they used slightly different terminology. This really complicated things for readers. I eventually realised there was a meta-principle here: in tech writing, the reader should never have to resol…
This gets even worse in software code. When "Naming things" is hard, and two people name the same thing, they'll very likely give it a different name. A guarantee to maintenance nightmares.
DDD by Eric Evans suggests using Ubiquitous Language. Even when I don't use anything from DDD, I always add a dictionary.md in which we write down the domain terms. What is a Customer? What does a "Loan Application" mean. What can we do to a loan application and how do we call those actions?
It's one of the easiest tricks, that dictionary.md, but with great effect.
Re: What I think about when I edit (2019)
#16I love this. Inevitably I want to make some improvements. > “He laughed with the kind of booming abandon that made the whole restaurant turn around and look.” The kind of ? If it's a kind that exists generically then we can't have a past tense, so: “He laughed with the kind of booming abandon that *makes* the whole restaurant turn around and look.” But really, why emphasise it being generic? This is better: “He laugh…
> “He laughed with a booming abandon that made the whole restaurant turn around and look.”
Don't the people in the restaurant actually turn around in this sentence, whereas they didn't in the original, because it's just describing a kind of loudness with an example?
> “He laughed with the kind of booming abandon that makes the whole restaurant turn around and look.”
Re: What I think about when I edit (2019)
#17Any other engineers trying to improve their writing skills? Any additional resources or tips to help me refine my drafting and editing process?
Death Sentence - The Decay of Public Language, by Don Watson.
Blisteringly good. Not aimed at technical writers, but encourages you to think about how to really use language effectively and robustly.
Re: What I think about when I edit (2019)
#18> You’ve heard this advice before. But you should understand why you shouldn’t use passive voice in your writing. It’s not just “bad style.” The ususal misunderstanding that everyone repeats. Read Williams‘, Clarity and Grace, or watch McEnerny‘s lecture on YouTube. Passive has its use, and it‘s not "to obscure who is doing the bad thing".
Williams’ book is really excellent. It deserves to be more widely read.
Re: What I think about when I edit (2019)
#19I was a doc reviewer in my corporate past life and found myself using many of these guidelines. I’d add one more: don’t use different names for the same thing. Many of the docs I reviewed had multiple authors and quite often they used slightly different terminology. This really complicated things for readers. I eventually realised there was a meta-principle here: in tech writing, the reader should never have to resol…
This gets even worse in software code. When "Naming things" is hard, and two people name the same thing, they'll very likely give it a different name. A guarantee to maintenance nightmares. DDD by Eric Evans suggests using Ubiquitous Language. Even when I don't use anything from DDD, I always add a dictionary.md in which we write down the domain terms. What is a Customer? What does a "Loan Application" mean. What can…
Why not put those definitions into the code, next to the types that define those entities?
Re: What I think about when I edit (2019)
#20My brain must be warped by using LLMs because I could not help but think that it would be an amazing prompt, complete with multiple examples of each principal. Perhaps good prompting is good writing?