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

31–40 of 138 posts

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

#31

Post by [deleted] »

jmmcd wrote: post #21
hovering_nox wrote: post #16

Earlier quoted context omitted.

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

[deleted]

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

#32

Post by publius_0xf3 »

>One of the best writing tips I've ever gotten was to avoid using demonstrative pronouns. Instead of saying “this” or “that,” you should add a noun to spell out exactly what you’re referring to, even if you’ve just mentioned it.

This piece of advice is maybe the only thing I remember from my college English class. A naked "this" or "that" now feels shamefully lazy to me.

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

#33

Post by ffsm8 »

medstrom wrote: post #26
valenterry wrote: post #19

Earlier quoted context omitted.

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?

> Your term may not map cleanly to a single OOP class

That's not really an argument, as it will map to either entities or functions, both of which can be annotated with this information.

An argument against documenting it on the entities and functions would be that this would spread the information across the repository. The value you get from doing this in a single markdown file is the overview it provides, I think.

These kinds of methodologies enable development with high turnover in large enterprise, which treat developers more like cogs that temporarily work on a given software. And if it's just a comment on a file, it'll likely not even be seen

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

#34

Post by KineticLensman »

publius_0xf3 wrote: post #32

>One of the best writing tips I've ever gotten was to avoid using demonstrative pronouns. Instead of saying “this” or “that,” you should add a noun to spell out exactly what you’re referring to, even if you’ve just mentioned it. This piece of advice is maybe the only thing I remember from my college English class. A naked "this" or "that" now feels shamefully lazy to me.

Totally agree! The worst example is a paragraph that starts with ‘this’. The author might remember what ‘this’ means at the time of writing, but other readers have to then insert themselves into the author’s stream of consciousness. ‘This’ paragraphs also make no sense when extracted from the main report, or to readers who are dipping in and out

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

#36

Post by bregma »

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

Well, yes, but one is telling and one is showing. A good story teller shows and not tells.

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

#37

Post by beezlebroxxxxxx »

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?

There are innumerable sources online for improving technical writing and they all generally repeat the same conventions and "rules". I tend to warn people, though, that over fixating on technical writing will not make you a great writer but just a capable technical writer.

If you're looking to improve your writing in general, then I think Joseph Williams' "Style: Towards Clarity and Grace" is the single best book on the subject written so far. Rather than simply state certain "rules", it methodically workshops examples to show how you can write and rewrite a sentence to change your meaning and emphasis at will.

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

#40

Post by zelphirkalt »

berkes wrote: post #15
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…

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…

I tried to introduce that, but few if any people stuck to it and still they came up with their own words and different understanding of the words that were already in the glossary I had created. It felt like they did not care much.
Post reply on HN