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

71–80 of 138 posts

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

#71

Post by berkes »

zelphirkalt wrote: post #40
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…

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, terrible products and quite often have a poor UX. I refuse to call these people software developers, instead I refer to them as code-monkeys. And with all the generative AI going on, these are the first to be replaced by robots in our fields.

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

#72

Post by berkes »

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?

For a large part, this can work. But there are several cases where it doesn't. Modules, subdirectories, a group of classes, etc. Too often, at least a part of the terms don't have a logical place to go in code. I consider it worse to have them partly here and partly there, than to have them all together.

But, indeed, I often repeat the definition or naming in the class documentation, module file, methods etc. Knowing fully well it will drift, but accepting it does. And everyone knows the canonical place is dictionary.md, inline docs are merely reminders or copies of that canonical place.

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

#74

Post by gghh »

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, just use an ordinary turbo encabulator". Why "just"? Are there other methods? For what reason is this the preferred one?

When giving advice: "Why don't you just use a bash script?" This implies your suggestion is simpler or more economical than my proposed approach, therefore better, but you aren't supporting its alleged superiority with arguments I can counter, only implying it.

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

#75

Post by hansvm »

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

> monads, "just"

I think that line is usually quoting a popular joke from a comedic tour of various programming languages, and "just" is appropriate.

> A monad is just a monoid in the category of endofunctors. What's the problem?

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

#76

Post by kd5bjo »

medstrom wrote: post #30
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.

In context, though, the passive version can sometimes make for smoother reading. My general rule of thumb is that each sentence should establish context at the beginning by referring to the preceding material and then introduce its new idea at the end— Whether it’s best to start with the maintainer or the pull request depends on which of those you’ve already been discussing. (I didn’t come up with this idea, but I unfortunately can’t remember where it came from)

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

#77

Post by zoya99 »

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 technical skills, let me know! You can contact me through the form on my website (https://evaparish.com/contact) or via LinkedIn.

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

#78

Post by gghh »

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.

Well, a copy editor maybe? https://en.wikipedia.org/wiki/Copy_editing

I've never used one, but I assume there are professionals for hire to do this.

In fact I've read one of the advantage of going with a publisher (as opposed to self-publishing) is they give you an editor. But again, I'd expect a freelance market to exist.

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

#79

Post by gghh »

hansvm wrote: post #75
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,…

> monads, "just" I think that line is usually quoting a popular joke from a comedic tour of various programming languages, and "just" is appropriate. > A monad is just a monoid in the category of endofunctors. What's the problem?

I see. It was the first sentence that came to mind. The point I'm trying to make is, in my experience, "just" is often abused, as it conveniently relieves one from providing a sound argument.

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

#80

Post by cookie_monsta »

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…

It's amazing that much of this has to be said, but here's a related piece of advice: don't use the same term for different things, especially if they're related.

I got a document the other day that described a category which consisted of 3 subcategories, one of which had the exact same name as the category it belonged to.

I felt like I had slipped into another dimension.

Post reply on HN