What words we should avoid?

twitter logo github logo ・1 min read

A lot of people heard about some words you should avoid in technical writing, for example, "simple", "just", "obvious". Because they can be removed most of the time without changing the sense of the sentence and they can make something seem easy when it isn't.

I wonder what else in this category?

I thought about one example recently "researchers say" unless you are quoting some research paper.

twitter logo DISCUSS (10)
markdown guide
 

I’m bad at knowing this, so I paid for Grammarly premium πŸ˜…

 

I like Antidote better (it does English and French - I need both). I did try Grammarly before Antidote introduced support for English and wasn't impressed at all (I threw some very common errors at it and it didn't flag any of them), but that was a few years ago.

 

One native speaker told me that Grammarly produces grammatically correct word soup

 
 

"only" is often a bit touchy, depending on context. "Clearly" may also be of some concern.

Incidentally, in Python, "obvious" has an altogether different meaning: it refers to a solution which, once known, is clearly the best solution to the problem, even as read by a relative novice to the language. (The "one obvious way" is sometimes not obvious while you're trying to solve the problem, a phenomenon mentioned in "The Zen of Python".)

However, the usage is completely different, so most uses of the word "obvious" still shouldn't escape the red pen in Python-oriented technical writing.

 

Are you talking about writing?

If so then here's a couple...

1. "this"

i.e.

Containers and Serverless are both great technology. This means that we can deploy apps quickly.

A (trite!) example but it showcases how this can be confusing as it can end up with multiple subjects. It nearly always makes sense to scan your work and replace "this" with a subject.

Containers and Serverless are both great technology. For Containers, that means that we can deploy apps quickly.

2. adverbs

More often than not they soften a sentence, consider removing them for more punch.

When it comes to Containers, they not really perfect for all tasks at hand.

Versus.

When it comes to Containers, they not perfect for all tasks at hand.

Also, I found this app to be a great tool: hemingwayapp.com

Don't go overboard with it, as it'll make your writing sound odd, but definitely consider it's suggestions.

As the old adage goes:

Kill your darlings! πŸ˜πŸ˜„

 

I've been thinking more about this, and the one I forgot was "all specific pronouns".

For a really long time, software documentation (especially open source) has pushed against the trend by using the pronoun "she" to refer to developers. "When a programmer decides to write a device driver, she usually thinks to do it in C", sort of thing.

The first demonstration user of a system is female - see any description of Alice and Bob.

That's kind of nice, and it's kind of jarring because we've been historically so used to reading "he" as the default pronoun for centuries.

But we don't want jarring, and "he" now reads just as badly to me. There's nothing wrong with using "they" in documentation and examples.

I notice on here, and on Twitter especially, a lot of people use "he" by default still, especially those for whom English is a second or third language. Teaching English as a foreign language either hasn't caught up with modern sensibilities or the speaker's native language has a firmer demand for a male default that they carry over.

We should encourage everyone to re-phrase documentation which refers to anyone with a gender-specific pronoun.

 

"So", "like", and "this", and for that matter anything that suddenly skips into present tense.

They're not objectionable in every context. It's more of a grammar niggle; because it instantly makes the writer look less professional.

So there's this framework and it's got this controller I've got a problem with it.

becomes

I have a problem with a framework and its controller.

 
Classic DEV Post from Aug 22

Where in the world do you DEV?

Show off where in the world you DEV from!

stereobooster profile image
Hello, I'm a full stack web developer. Follow me on Twitter!

Do you prefer sans serif over serif?

You can change your font preferences in the "misc" section of your settings. ❀️