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

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

#81

Post by aorth » Sat, Apr 06, 2024, 1:36 PM UTC

gghh wrote: post #74

If I could add one prescription to TFA, it would be to avoid using "just" (the adverb, as in "simply") at all costs. "A monad is just a monoid in the category of endofunctors." Maybe it is, maybe it isn't, but none of that is simple. There's that math joke about proof methods, and this would be "proof by intimidation". When describing a process: "To measure the inverse reactive current in unilateral phase detractors,…

Yes, good suggestion. I've also stopped using "just" when speaking or writing in the last few years. You can almost always drop it and retain the same meaning without sounding rude or dismissive.

I've noticed this in at least one other language I'm loosely familiar with (Bulgarian) and it holds there too. When the speaker adds "просто" it has the same effect of sounding rude and dismissive.

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

#82

Post by gghh » Sat, Apr 06, 2024, 1:50 PM UTC

aorth wrote: post #81

gghh wrote: post #74

If I could add one prescription to TFA, it would be to avoid using "just" (the adverb, as in "simply") at all costs. "A monad is just a monoid in the category of endofunctors." Maybe it is, maybe it isn't, but none of that is simple. There's that math joke about proof methods, and this would be "proof by intimidation". When describing a process: "To measure the inverse reactive current in unilateral phase detractors,…

Yes, good suggestion. I've also stopped using "just" when speaking or writing in the last few years. You can almost always drop it and retain the same meaning without sounding rude or dismissive. I've noticed this in at least one other language I'm loosely familiar with (Bulgarian) and it holds there too. When the speaker adds "просто" it has the same effect of sounding rude and dismissive.

Right: rude, dismissive, patronizing. Gives me exactly this impression, you put it into words better than me.

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

#83

Post by swayvil » Sat, Apr 06, 2024, 2:02 PM UTC

This is smart stuff. All of it makes good sense. I speak as a compulsive editor.

You can tighten it up, and tighten it up again, and sloppy doggerel becomes so clear.

Really a lovely piece of writing about writing.

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

#84

Post by swayvil » Sat, Apr 06, 2024, 2:06 PM UTC

lootsauce wrote: post #20

My 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?

I thought the same.

(I did something similar in drawing. So it's a not uncommon path)

Get your art sharp. Digest that into a science. Digest the science into automation.

(And yes, one could argue that the result is a crystalline turd.)

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

#85

Post by brainzap » Sat, Apr 06, 2024, 2:09 PM UTC

susam wrote: post #43

One of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and over again across several documents of a project and people working on the project change over years, sometimes we end up in a situation where nobody can tell anymore what a particular acronym expands to. In fact, more than once, I have seen the bizarre situation…

I think the google guide to technical writing recommends to write out acronyms once per chapter/section.

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

#86

Post by hcarvalhoalves » Sat, Apr 06, 2024, 2:15 PM UTC

HeavyStorm wrote: post #45

susam wrote: post #43

One of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and over again across several documents of a project and people working on the project change over years, sometimes we end up in a situation where nobody can tell anymore what a particular acronym expands to. In fact, more than once, I have seen the bizarre situation…

A glossary is the most important document ANY project should have and maintain. Everything else is secondary.

Agree. A glossary is a way to introduce a domain piecemeal, without a long-form explanation.

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

#87

Post by alphazard » Sat, Apr 06, 2024, 2:21 PM UTC

I've heard English teachers cargo cult the passive voice thing for ever.

This crowd will understand the passive voice as a form of abstraction. If anything could suffice as the subject, then it's not important to the meaning of the sentence, and you convey that in English by implying but not specifying the subject (the passive voice).

In scientific procedures for example, the whole point is that anyone could replicate it. 30 grams of goop was added to the beaker. Doesn't matter if it was you or one of your coworkers, or another group trying to replicate.

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

#88

Post by natdempk » Sat, Apr 06, 2024, 2:32 PM UTC

alphazard wrote: post #87

I've heard English teachers cargo cult the passive voice thing for ever. This crowd will understand the passive voice as a form of abstraction. If anything could suffice as the subject, then it's not important to the meaning of the sentence, and you convey that in English by implying but not specifying the subject (the passive voice). In scientific procedures for example, the whole point is that anyone could replicat…

When I learned about passive voice, scientific writing was often mentioned as an explicit exception. What you say makes sense when you are abstractly describing something that happened, but also I'd argue that "We added 30 grams of goop to the beaker" or "Added 30 grams of goop to the beaker" is clearer than "30 grams of goop was added to the beaker". Depends on the context and style conventions of course, but often passive voice is still poor/indirect writing in many scientific contexts.

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

#89

Post by tpoacher » Sat, Apr 06, 2024, 2:41 PM UTC

susam wrote: post #43

One of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and over again across several documents of a project and people working on the project change over years, sometimes we end up in a situation where nobody can tell anymore what a particular acronym expands to. In fact, more than once, I have seen the bizarre situation…

I'm always tempted to go passive-aggressive and misinterpret the acronym. I don't, but I'm tempted to.

E.g. "Couldn't we simply write an email to the Computer, Data, and Information Services department for the access token? This keeps a paper trail, and explains why you need Digital Media Credentials in the first place."

I'm someone who's jumped from Medicine to CompSci. Each field uses their own obscure acronyms that highly intersect. I'll spare you the embarrassment that comes from someone making a "Pro Rectum" request.

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

#90

Post by grok22 » Sat, Apr 06, 2024, 3:15 PM UTC

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…

It feels like your change is changing the scene? The author's sentence makes it seem like the laughter was not in the restaurant, while yours makes it seem like it's taking place in the restaurant. Maybe I am overthinking it!