Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

What I think about when I edit (2019)

evaparish.com

Post reply on HN
Print view View original

21–30 of 138 posts

Re: What I think about when I edit (2019)

#21

Post by jmmcd »

hovering_nox wrote: post #16
jmmcd wrote: post #10

I 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.”

> Don't the people in the restaurant actually turn around in this sentence, whereas they didn't in the original

No, the original said "made", so I think they actually turned around.

Re: What I think about when I edit (2019)

#22

Post by jmmcd »

wizzwizz4 wrote: post #14
jmmcd wrote: post #10

I 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."

We now live in a sad, post-apocalyptic world, with no booming, no abandon, no turning around, and very few people in restaurants.

Re: What I think about when I edit (2019)

#23

Post by lawn »

hubraumhugo wrote: post #4

Any other engineers trying to improve their writing skills? Any additional resources or tips to help me refine my drafting and editing process?

I've been trying to improve by making a conscious effort to practice it. I've been trying to blog and even wrote a book, partly to increase my writing skills.

The book that helped me the most is On Writing Well: The Classic Guide to Writing Nonfiction.

I also wrote a blog post about some of the lessons I learned:

https://www.jonashietala.se/blog/2023/11/25/writing_lessons_...

Re: What I think about when I edit (2019)

#24

Post by microflash »

Tomte wrote: post #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".

Indeed. However, it is the most oft-repeated consequence of using Passive voice. In general, I use active voice and when it makes sense, passive voice is used as well.

Re: What I think about when I edit (2019)

#25

Post by ano-ther »

All great advice. Except for “avoid passive”.

It’s a part of the toolbox that changes the perspective on an action.

“The pull request got merged” vs. “The maintainer merged the pull request”.

If i want to talk about the new feature that gets implemented by the pull request, then I mislead the reader by emphasizing the maintainer, rather than the pull request.

The passive also allows you to choose whether you want to call out the source of an action.

“The pull request got merged by the maintainer.”

Yes, you can misuse it to fudge responsibility, but you don’t need the passive to do that.

Re: What I think about when I edit (2019)

#26

Post by medstrom »

valenterry wrote: post #19
berkes wrote: post #15

Earlier quoted context omitted.

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?

Your term may not map cleanly to a single OOP class, and it may also be used in other function/variable names. There's also how you will express yourself in the code comments.

I mean, I'm guessing the dictionary is not just for nouns, but also verbs and adverbs. What will "transact" usually mean in this codebase? What will "safely" mean?

Re: What I think about when I edit (2019)

#28

Post by RheingoldRiver »

This is a fantastic list of like, "suggestions to writers by editors" but I don't think it's a great list of "how to edit." The single most important thing when editing (imo) is "how can I preserve the author's voice?" Editing is not writing a new draft, it's amplifying the original.

Re: What I think about when I edit (2019)

#29

Post by RheingoldRiver »

hubraumhugo wrote: post #4

Any other engineers trying to improve their writing skills? Any additional resources or tips to help me refine my drafting and editing process?

Developing Quality Technical Information - https://www.amazon.com/Developing-Quality-Technical-Informat...

My review + some notes - https://river.me/blog/book-review-quality-technical-informat... (it's very good)

Re: What I think about when I edit (2019)

#30

Post by medstrom »

ano-ther wrote: post #25

All great advice. Except for “avoid passive”. It’s a part of the toolbox that changes the perspective on an action. “The pull request got merged” vs. “The maintainer merged the pull request”. If i want to talk about the new feature that gets implemented by the pull request, then I mislead the reader by emphasizing the maintainer, rather than the pull request. The passive also allows you to choose whether you want to…

"They merged the pull request" sounds fine to me.
Post reply on HN