4 ms·

This is such a bizarre take. The post is about removing some unnecessary wording from technical documentation that doesn't add anything, and as an aside can som

by smcl 4y ago

This is such a bizarre take. The post is about removing some unnecessary wording from technical documentation that doesn't add anything, and as an aside can sometimes imply complex tasks are simpler than they are to the detriment of the app/library/service it's documenting. I have no idea why you'd think this implies some personal failing or that it is advice for "babies"

warent 4y ago
Agree wholeheartedly. Most people are comfortable making incremental improvements in all our tools and comforts in life, so why should communication (the greatest tool of all!) be any different? We can make a knife with a better handle or keyboard with better shape, and it's called "ergonomic." Nobody claims someone being a baby for wanting that. Meanwhile, a small suggestion to enhance how we handle communication is met with such severity and perceptual distortions, as though the ones making the suggestions are having some breathless emotional psychosis. Why?
codeflo 4y ago
> The post is about removing some unnecessary wording from technical documentation that doesn't add anything, and as an aside can sometimes imply complex tasks are simpler than they are to the detriment of the app/library/service it's documenting. I'm not sure that's a fair summary of the article. I just reread it: at no point does it suggest removing superfluous words in general, it's specifically about "words such as easy, painless, straightforward, trivial, simple and just", because those in particular are "jolting", "upsetting and annoying" and "infuriating". What you frame as an "aside" is in fact the first and last paragraph of the article. > I have no idea why you'd think this implies some personal failing or that it is advice for "babies" You're missing a level of indirection here, the readers of the documentation are the “babies”, not the writers who take this article's advice. This is advice for people who write for people who act offended when reading the word "simply" in technical documentation, and I'm questioning the dynamics of that. It's obviously fair to criticize the word choice on my part, there were less incisive ways to phrase that. But then, it's the article that claims that the usage of the word "just" in the sentence (the article's example) "[then] we will just edit the users_controller.rb" is "condescending", and I think that's "simply" (sic) insane.
- zabzonk 4y ago
  john lennon once said "never use 'just' in a lyric - it's lazy" (i paraphrase) and i think he might have had simmilar opinions on such things as "trivial". sadly, we will never know.
  - lowercased 4y ago
    * He used 'trivialities' in a song (When I Get Home) * She was "just" seventeen (arguably that was Paul's line, but John didn't override it, and kept his name on it) * "(Just like) Starting Over" has 'just' in the title and lyrics. * "Just" gimme some truth. * "I'm just a jealous guy" Rules are meant to be broken, perhaps? Or maybe he would just cop to being lazy?
    - deleted 4y ago
      [deleted]
    - zabzonk 4y ago
      > Rules are meant to be broken, perhaps? Or maybe he would just cop to being lazy? both? the quote i paraphrased was from hunter davies' authorised biog of the beatles but i still think it is a good rule
      - lowercased 3y ago
        i don't completely disagree. I wonder how much of that was a flippant remark, how much his own views changed in the intervening years.
nonethewiser 4y ago
> The post is about Please reread the comment you are replying to. He’s talking about the hacker news comments.
- warent 4y ago
  The very first sentence of their comment is an appeal to the article. They're addressing the article and using HN comments as evidence to reinforce their perception of it. "Stop saying how simple things are in our docs" "Or maybe -- controversial opinion here -- people shouldn't be such babies"
  - cal85 4y ago
    Yes, it’s possible to alter the meaning of something by quoting a sentence out of context. If you continue reading to the next sentence, it becomes explicitly clear that he is addressing the comments here.
avereveard 4y ago
> that doesn't add anything tbh I enjoy when documentation gives me an idea of the effort required to go trough it. is it just copy pasting commands? does it require any configuration for achieving different goal? am I supposed to handle prerequisites on my own? Is there any passage that require my attention or everything will break down the line? now, "simple" may not be the correct wording for it, but still I wouldn't say that there's no value in indicating the effort beforehand.

by smcl 4y ago

warent 4y ago

Agree wholeheartedly. Most people are comfortable making incremental improvements in all our tools and comforts in life, so why should communication (the greatest tool of all!) be any different? We can make a knife with a better handle or keyboard with better shape, and it's called "ergonomic." Nobody claims someone being a baby for wanting that. Meanwhile, a small suggestion to enhance how we handle communication is met with such severity and perceptual distortions, as though the ones making the suggestions are having some breathless emotional psychosis. Why?

codeflo 4y ago

> The post is about removing some unnecessary wording from technical documentation that doesn't add anything, and as an aside can sometimes imply complex tasks are simpler than they are to the detriment of the app/library/service it's documenting. I'm not sure that's a fair summary of the article. I just reread it: at no point does it suggest removing superfluous words in general, it's specifically about "words such as easy, painless, straightforward, trivial, simple and just", because those in particular are "jolting", "upsetting and annoying" and "infuriating". What you frame as an "aside" is in fact the first and last paragraph of the article. > I have no idea why you'd think this implies some personal failing or that it is advice for "babies" You're missing a level of indirection here, the readers of the documentation are the “babies”, not the writers who take this article's advice. This is advice for people who write for people who act offended when reading the word "simply" in technical documentation, and I'm questioning the dynamics of that. It's obviously fair to criticize the word choice on my part, there were less incisive ways to phrase that. But then, it's the article that claims that the usage of the word "just" in the sentence (the article's example) "[then] we will just edit the users_controller.rb" is "condescending", and I think that's "simply" (sic) insane.

zabzonk 4y ago
john lennon once said "never use 'just' in a lyric - it's lazy" (i paraphrase) and i think he might have had simmilar opinions on such things as "trivial". sadly, we will never know.
- lowercased 4y ago
  * He used 'trivialities' in a song (When I Get Home) * She was "just" seventeen (arguably that was Paul's line, but John didn't override it, and kept his name on it) * "(Just like) Starting Over" has 'just' in the title and lyrics. * "Just" gimme some truth. * "I'm just a jealous guy" Rules are meant to be broken, perhaps? Or maybe he would just cop to being lazy?
  - deleted 4y ago
    [deleted]
  - zabzonk 4y ago
    > Rules are meant to be broken, perhaps? Or maybe he would just cop to being lazy? both? the quote i paraphrased was from hunter davies' authorised biog of the beatles but i still think it is a good rule
    - lowercased 3y ago
      i don't completely disagree. I wonder how much of that was a flippant remark, how much his own views changed in the intervening years.

nonethewiser 4y ago

> The post is about Please reread the comment you are replying to. He’s talking about the hacker news comments.

warent 4y ago
The very first sentence of their comment is an appeal to the article. They're addressing the article and using HN comments as evidence to reinforce their perception of it. "Stop saying how simple things are in our docs" "Or maybe -- controversial opinion here -- people shouldn't be such babies"
- cal85 4y ago
  Yes, it’s possible to alter the meaning of something by quoting a sentence out of context. If you continue reading to the next sentence, it becomes explicitly clear that he is addressing the comments here.

avereveard 4y ago

> that doesn't add anything tbh I enjoy when documentation gives me an idea of the effort required to go trough it. is it just copy pasting commands? does it require any configuration for achieving different goal? am I supposed to handle prerequisites on my own? Is there any passage that require my attention or everything will break down the line? now, "simple" may not be the correct wording for it, but still I wouldn't say that there's no value in indicating the effort beforehand.