What I think about when I edit (2019) • Hacker News Board

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

#91

Post by Scubabear68 » Sat, Apr 06, 2024, 3:37 PM UTC

This post is a great set of ideas for writing. What the author is doing is constantly putting himself in the shoes of the readers, and thinking “what does the reader need here?”.

Which may sound like a very tortuous way to write. But it becomes instinctual after a while. When I’m writing and don’t apply rules like this, I inevitably feel lost - and I know the reader will be too. When I end up going down a bad road like this, at some point I will throw away most or all of what I’ve written and start from a fresh perspective. I guess this would be my one addition to the author’s rules: don’t be afraid to throw away lines, paragraph, or even the whole thing if it’s not working for you.

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

#92

Post by mattbee » Sat, Apr 06, 2024, 3:38 PM UTC

richrichie wrote: post #27

richrichie wrote: post #11

Original source found at: https://www.gutenberg.org/ebooks/37134

Some HN folks here are so thin skinned that they down vote a reference to Strunk and White?

It's definitely nothing new but good advice bears repeating over the decades :)

For big picture stuff on writing I also like "On Writing Well" by William Zissner and "First You Write A Sentence" by Joe Moran (which is a bit more British).

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

#93

Post by tomsmeding » Sat, Apr 06, 2024, 4:22 PM UTC

cs02rm0 wrote: post #67

Is there a service for this? (Standard developer question). I found myself writing a book recently, completely left field to my normal technical work. I'm intending on approaching a literary agent but I need it reviewed first and I'm looking for dispassionate, distanced, but informed opinions.

> completely left field to my normal technical work.

I'm assuming this is another baseball reference. As a non-American: what does it mean? :)

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

#94

Post by jodrellblank » Sat, Apr 06, 2024, 4:23 PM UTC

gghh wrote: post #66

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

Thanks for the references. I'll check them. I'm extremely biased against the business use of passive voice, to the point of getting so worked up when someone does it with me on mail or slack, that I need go to a quite room and relax for 5 minutes. The purchase order has been made. Your virtual machine has been created. I see this a lot in corporate environments, and it's by low level managers thinking every bit of in…

The opposite:

"I've just created your virtual machine" - 3 year old, "mummy, mummy, /I/ did this! praise ME!". Got to insert yourself as the first thing in the sentence, as if the customer cares who did it.

"Your virtual machine is ready" - Waiter, assistant, comfortable out of the limelight to let the focus be on the customer and what they are interested in.

"I've just created your virtual machine" - You didn't make the deployment pipeline, you didn't build the hosting, or write any of the hypervisor or guest OS, you ran one script and now you're taking all the credit. Embarrassing.

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

#95

Post by gghh » Sat, Apr 06, 2024, 4:47 PM UTC

jodrellblank wrote: post #94

gghh wrote: post #66

Earlier quoted context omitted.

Thanks for the references. I'll check them. I'm extremely biased against the business use of passive voice, to the point of getting so worked up when someone does it with me on mail or slack, that I need go to a quite room and relax for 5 minutes. The purchase order has been made. Your virtual machine has been created. I see this a lot in corporate environments, and it's by low level managers thinking every bit of in…

The opposite: "I've just created your virtual machine" - 3 year old, "mummy, mummy, /I/ did this! praise ME!". Got to insert yourself as the first thing in the sentence, as if the customer cares who did it. "Your virtual machine is ready" - Waiter, assistant, comfortable out of the limelight to let the focus be on the customer and what they are interested in. "I've just created your virtual machine" - You didn't make…

Good point. Focus on the customer. Didn't see that aspect.

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

#96

Post by svat » Sat, Apr 06, 2024, 4:56 PM UTC

richrichie wrote: post #27

richrichie wrote: post #11

Original source found at: https://www.gutenberg.org/ebooks/37134

Some HN folks here are so thin skinned that they down vote a reference to Strunk and White?

Was your comment (“Original source found at…”) intended to be a reply to some other comment, rather than being a top-level comment? Or did you actually mean to suggest that the original source of the post here (“What I think about when I edit (2019)”) is Strunk and White? The latter seems pretty misleading and inappropriate.

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

#97

Post by k__ » Sat, Apr 06, 2024, 5:04 PM UTC

I needed the repetition tip the most.

I always feel like repeating myself makes the text unwieldy and then clutter it with "this".

Grammarly always complains, "What is this refering to?"

Well, obviously a concept of the previous sentence!

I will repeat myself more often and then rephrase the repetition.

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

#98

Post by BossingAround » Sat, Apr 06, 2024, 5:13 PM UTC

I would add eliminating future tense. There's very few times when future tense is actually required. It's one of my pet peeves when docs say something like "Click X. This will open a prompt ..." when it can say "Click x. This opens a prompt ..."

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

#99

Post by BossingAround » Sat, Apr 06, 2024, 5:16 PM UTC

k__ wrote: post #97

I needed the repetition tip the most. I always feel like repeating myself makes the text unwieldy and then clutter it with "this". Grammarly always complains, "What is this refering to?" Well, obviously a concept of the previous sentence! I will repeat myself more often and then rephrase the repetition.

Honestly, I would recommend never using "this" or "that" - it often makes sense only after you force the reader to re-read the sentence.

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

#100

Post by euroderf » Sat, Apr 06, 2024, 5:25 PM UTC

KineticLensman wrote: post #9

I 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…

> don’t use different names for the same thing.

But if there ARE different names, call it out in the introduction, and state which one you will be using.