7 ms·

It's a more and more popular opinion: - Why not tell people to "simply" use pyenv, poetry or anaconda (https://bitecode.substack.com/p/why-not-tell-people-to-s

It's a more and more popular opinion: - Why not tell people to "simply" use pyenv, poetry or anaconda (https://bitecode.substack.com/p/why-not-tell-people-to-simply-use https://bitecode.substack.com/p/why-not-tell-people-to-simpl...) - Don’t use the word ‘simply’ (https://jameshfisher.com/2017/02/22/dont-use-simply/ https://jameshfisher.com/2017/02/22/dont-use-simply/) - Stop using ‘simply’ in tech instructions (https://www.parkersoftware.com/blog/stop-using-simply-in-tech-instructions/ https://www.parkersoftware.com/blog/stop-using-simply-in-tec...) - Don’t say “simply” in your documentation (https://www.knowledgeowl.com/blog/posts/dont-say-simply-jim-fisher/ https://www.knowledgeowl.com/blog/posts/dont-say-simply-jim-...) And I strongly agree. It can be so discouraging to fail at something you should "simply" do. But to be fair to the technical writers, it's easy to write that way without noticing, even after proof reading. This should be automatized by writing tools. Also, while it's mildly irritating, there are worse things in life. Yet as the first link about the python ecosystems notes, it usually hides a bigger problem: many devs are too good to be helpful.

kqr 3y ago
I remember reading one of those and it made a huge impression on me. I've followed it ever since and taught others to do the same. As far as I can tell, it has only been met with appreciation. That said, sometimes I find myself trying to write around "simple" when I really mean "less complex", and I have to remind myself that what I really want to avoid is implying "easy", not "relatively less complex".
- sametmax 3y ago
  Indeed. I tend to force myself to write the following: - It will be easy => I will guide you through it - This will make your life easy => It will make your life easier / It will help you - To do X, simply do Y => The most common way to get to X is first to do Y
- sjrd 3y ago
  You can use comparatives, like "simpler", usually without issues. Something can be simpler than something else without necessarily being simple. Superlatives like "simplest" can sometimes be used as well. After all, being the simplest thing means to be simpler than all the other things; still not necessarily simple. It's only the positive form "simple" which is problematic and should be almost always avoided.
  - kqr 3y ago
    This is indeed where I usually go. "Under condition X, it is simpler to Y" rather than "Under condition X, you can simply Y."
wdfx 3y ago
Similarly, one should never state that something is "obvious". I catch myself sometimes starting a sentence with "Obviously," and usually stop myself at that point and restart.
- BiteCode_dev 3y ago
  True, there is no such thing as a concept been obvious to everybody. Feyman has this great bit in his biography where he tackles mathematicians that keep saying in their demonstration that a step is trivial.
- Fnoord 3y ago
  Clearly, there are other words which sound condescending. Reading text (documentation, for example) is more enjoyable when it inspires one's curiosity instead of belittling them on things which are simple, easy, obvious, clear, etc. Although humor helps, makes it stick.
  - wongarsu 3y ago
    > Clearly, there are other words which sound condescending. Well played. You start with a synonym for obviously, but pointing that out just proves your point. Maybe there are some sentences that can justifiably start with obviously, clearly, etc after all
- opan 3y ago
  I often reply back quietly or in my head "obviously" with a bit of a laugh when I hear it used. It usually sounds absurd and unnecessary and takes me out of what was being said.
- Semaphor 3y ago
  "Obviously" will always remind me of math classes in university. Sometimes the professor would use it as a joke, sometimes they used it normally while still stumping everyone else.
- adolph 3y ago
  At first I agreed with you in that my spouse had a negative response to me referring to a particular person, method, place or thing as “famous” when she was not aware of the person. I’ve learned to omit it or say “well known in some circles” or the like. On the other hand, maybe these phrases like “simply” or “obviously”are less-than-consciously used on the part of the speaker/writer to acknowledge that this reference may already be known to the listener/reader. In that it reminds me of various England-Englishisms that mean the opposite of their plain definitions.
gv83 3y ago
it's not only the word `simply`; I find myself perusing more and more docs that boil down to an emoji-laden slab of super-shallow tutorials and marketing lingo, which just tell you how to do the most basic thing - or the barely less basic thing in the most ideal scenario - and nothing more. I'm all ok with tutorials and examples into the docs, but give some depth to them, not only breadth (or emojis).
WastingMyTime89 3y ago
"Simply" when used in the sense of "without addition, alone" is perfectly fine. I find the issue people have is not really with the word simply but with bad documentation and badly designed tools. That’s not going to be fixed by avoiding one word.
- fnordsensei 3y ago
  “Simple” vs “easy”: https://youtu.be/LKtk3HCgTa8 https://youtu.be/LKtk3HCgTa8
- lucakiebel 3y ago
  Ok, so at least I‘m not the only one using simply that way
latexr 3y ago
> This should be automatized by writing tools. iA Writer¹ does it. It strikes out and greys out the words “simply” and “just” as part of its style check for fillers. ¹ https://ia.net/writer https://ia.net/writer
- Osiris 3y ago
  The intro video for that app is one of the best I’ve seen in explaining quickly the value proposition of the software. Many websites for software use so many buzzwords or marketing language as to not effectively communicate the value of the software.
WesolyKubeczek 3y ago
Monty Python’s sketch “How to Do It” has some decades.
everybodyknows 3y ago
In the case of documentation provided by the creators of the software, there's a more substantial vexation: Use of such words comes off as vacuous, self-praising bullshit.

kqr 3y ago

I remember reading one of those and it made a huge impression on me. I've followed it ever since and taught others to do the same. As far as I can tell, it has only been met with appreciation. That said, sometimes I find myself trying to write around "simple" when I really mean "less complex", and I have to remind myself that what I really want to avoid is implying "easy", not "relatively less complex".

sametmax 3y ago
Indeed. I tend to force myself to write the following: - It will be easy => I will guide you through it - This will make your life easy => It will make your life easier / It will help you - To do X, simply do Y => The most common way to get to X is first to do Y
sjrd 3y ago
You can use comparatives, like "simpler", usually without issues. Something can be simpler than something else without necessarily being simple. Superlatives like "simplest" can sometimes be used as well. After all, being the simplest thing means to be simpler than all the other things; still not necessarily simple. It's only the positive form "simple" which is problematic and should be almost always avoided.
- kqr 3y ago
  This is indeed where I usually go. "Under condition X, it is simpler to Y" rather than "Under condition X, you can simply Y."

wdfx 3y ago

Similarly, one should never state that something is "obvious". I catch myself sometimes starting a sentence with "Obviously," and usually stop myself at that point and restart.

BiteCode_dev 3y ago
True, there is no such thing as a concept been obvious to everybody. Feyman has this great bit in his biography where he tackles mathematicians that keep saying in their demonstration that a step is trivial.
Fnoord 3y ago
Clearly, there are other words which sound condescending. Reading text (documentation, for example) is more enjoyable when it inspires one's curiosity instead of belittling them on things which are simple, easy, obvious, clear, etc. Although humor helps, makes it stick.
- wongarsu 3y ago
  > Clearly, there are other words which sound condescending. Well played. You start with a synonym for obviously, but pointing that out just proves your point. Maybe there are some sentences that can justifiably start with obviously, clearly, etc after all
opan 3y ago
I often reply back quietly or in my head "obviously" with a bit of a laugh when I hear it used. It usually sounds absurd and unnecessary and takes me out of what was being said.
Semaphor 3y ago
"Obviously" will always remind me of math classes in university. Sometimes the professor would use it as a joke, sometimes they used it normally while still stumping everyone else.
adolph 3y ago
At first I agreed with you in that my spouse had a negative response to me referring to a particular person, method, place or thing as “famous” when she was not aware of the person. I’ve learned to omit it or say “well known in some circles” or the like. On the other hand, maybe these phrases like “simply” or “obviously”are less-than-consciously used on the part of the speaker/writer to acknowledge that this reference may already be known to the listener/reader. In that it reminds me of various England-Englishisms that mean the opposite of their plain definitions.

gv83 3y ago

it's not only the word `simply`; I find myself perusing more and more docs that boil down to an emoji-laden slab of super-shallow tutorials and marketing lingo, which just tell you how to do the most basic thing - or the barely less basic thing in the most ideal scenario - and nothing more. I'm all ok with tutorials and examples into the docs, but give some depth to them, not only breadth (or emojis).

WastingMyTime89 3y ago

"Simply" when used in the sense of "without addition, alone" is perfectly fine. I find the issue people have is not really with the word simply but with bad documentation and badly designed tools. That’s not going to be fixed by avoiding one word.

fnordsensei 3y ago
“Simple” vs “easy”: https://youtu.be/LKtk3HCgTa8 https://youtu.be/LKtk3HCgTa8
lucakiebel 3y ago
Ok, so at least I‘m not the only one using simply that way

latexr 3y ago

> This should be automatized by writing tools. iA Writer¹ does it. It strikes out and greys out the words “simply” and “just” as part of its style check for fillers. ¹ https://ia.net/writer https://ia.net/writer

Osiris 3y ago
The intro video for that app is one of the best I’ve seen in explaining quickly the value proposition of the software. Many websites for software use so many buzzwords or marketing language as to not effectively communicate the value of the software.

WesolyKubeczek 3y ago

Monty Python’s sketch “How to Do It” has some decades.

everybodyknows 3y ago

In the case of documentation provided by the creators of the software, there's a more substantial vexation: Use of such words comes off as vacuous, self-praising bullshit.