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

121–130 of 138 posts

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

#121

Post by anamax »

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…

The flip side of "don't use different names for the same thing" is "don't use the same/similar name for different things."

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

#122

Post by ripe »

KineticLensman wrote: post #65
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…

I was once caught in a contractual dispute that occurred because the author used passive. The contract basically said 'X will be done' without identifying whether the customer or contractor was expected to do X. Unfortunately this wasn't spotted until the contract was in place. If you must use passive in situations like these, please at least identify the agent, e.g. "X will be done by Y". Oy just use the shorter, ex…

> Unfortunately this wasn't spotted until the contract was in place.

Sorry, couldn't resist pointing out this use of the passive voice.

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

#123

Post by oefnak »

zoya99 wrote: post #77

Hello everyone! This is my post! I'm flattered and honored that it resonated with many of you. Since I wrote that post, I followed my curiosity to become a software engineer myself. After doing that work for a few years, I've found myself missing working in a more writing-heavy role. If you're looking for an excellent technical writer, developer advocate, or another role that blends communication expertise and techni…

You using HTTP in the example without explaining it, was really funny. Was that joke on purpose?

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

#124

Post by ffsm8 »

coldtea wrote: post #46
ffsm8 wrote: post #33

Earlier quoted context omitted.

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

> That's not really an argument, as it will map to either entities or functions, both of which can be annotated with this information. No, it might not map to entities or functions. It could refer to concepts about the project that are not mapped in the code, but are still important to communicate with the team, the customers, and so on. And even for terms that do map to entities and functions, it would be a bad idea…

> Even small teams of 4-10 people can benefit from shared common terminology

The team size has very little impact on it's value, it's entirely dependent on the turnover of the developers. I guess I wasn't clear enough as it seems you didn't understand what I meant to express at all.

With every sentence you wrote I just had another question mark appear over my head

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

#126

Post by keybored »

berkes wrote: post #71
zelphirkalt wrote: post #40

Earlier quoted context omitted.

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.

> It felt like they did not care much. If software people don't care about using the business-domain-language, I think they are very bad software developers. The main task of software developers is to be the bridge between the domain and computers. I've met and seen my share of teams that don't want to be that bridge, or offload it to "product owners" or "managers". They are -without exception- abysmal projects, terr…

It doesn’t sound hard for LLMs to act as a domain-computer bridge.

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

#127

Post by gghh »

chungmin wrote: post #117
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,…

What is TFA?

What I meant by it is "the fine article", meaning the post. Actually using acronyms goes against "Don't assume knowledge", incidentally a point in Eva's list (the article).

I've learned the acronym here on HN, googled for a second and found "the fine article" as explanation, but now that you ask I've checked wiktionary... and apparently the commonly accepted meaning is derogatory (the f*king article, like "RTFM", "read the F-ing manual).

Lesson learned, won't be saying "TFA" again unless I mean f-ing

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

#128

Post by medstrom »

coldtea wrote: post #58
medstrom wrote: post #30

Earlier quoted context omitted.

"They merged the pull request" sounds fine to me.

As the parent notes though, "the passive also allows you to choose whether you want to call out the source of an action", while "they merged the pull request" does not.

That part, I do not get. Do they mean it permits a rewrite? But all sentences do.

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

#129

Post by roryokane »

quaddo wrote: post #118

Back around 20 years ago I was with an MSP. We depended heavily on having a well written - as current as possible - prod guide for all operations. At some point it occurred to me that there was likely a way to draw upon the experiences of those who came before us. In my case, it seemed fitting to use newspapers as a reference. Somewhere I’d come across a concise guideline, a list of do’s and don’ts. The only thing I…

What is an MSP?

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

#130

Post by KineticLensman »

ripe wrote: post #122
KineticLensman wrote: post #65

Earlier quoted context omitted.

I was once caught in a contractual dispute that occurred because the author used passive. The contract basically said 'X will be done' without identifying whether the customer or contractor was expected to do X. Unfortunately this wasn't spotted until the contract was in place. If you must use passive in situations like these, please at least identify the agent, e.g. "X will be done by Y". Oy just use the shorter, ex…

> Unfortunately this wasn't spotted until the contract was in place. Sorry, couldn't resist pointing out this use of the passive voice.

ha!

In my defence I was demonstrating the way that passive voice can also be used to obscure responsibility after the event, as in "mistakes were made"

Post reply on HN