[hliyan]

Particularly satisfying to see this section calling out a lot of business jargon: https://stylepedia.net/style/#avoiding-confusing-language

e.g.

best-of-breed

Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type". Other alternatives include best, foremost, most advanced, and optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims.

bleeding edge

Do not use.

boil the ocean

Do not use. State exactly what you mean, such as "increase the scope hugely".

[Cthulhu_]

It makes sense too when you fully understand your audience isn't exclusively English; expressions will be more difficult to read for ESL, and difficult if not impossible to translate to a non-English language. And the docs site is available in 8 different languages.

With translation tools (from the past... 3 decades, starting with Babelfish) and modern-day documentation processing / retrieval tools (LLMs), simplicity, clarity and consistency are even more important. But it's timeless advice.

[froobius]

Funny thing is that to people who use those terms regularly, they are "stating exactly what they mean".

I.e. "increase the scope hugely", the word "scope" itself comes from greek with its core meaning revolving around "viewing" or "looking". It's only because we are all familiar with it also meaning the scale / amount of things a project should cover, that we all understand. (I guess there's a metaphor of the project "looking over" more as the number / magnitude of goals increases.)

So it shouldn't be "state exactly what you mean", because they are.

It should be more like: "state what you mean using widely used language if possible"