Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Just Simply – Stop saying how simple things are in our docs

justsimply.dev

Post reply on HN
Print view View original

101–110 of 299 posts

Re: Just Simply – Stop saying how simple things are in our docs

#101

Post by opan »

wdfx wrote: post #38
sametmax wrote: post #3

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-simpl... ) - Don’t use the word ‘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-tec... ) - Don’t say “simply” in your documentation ( https:/…

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.

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.

Re: Just Simply – Stop saying how simple things are in our docs

#102

Post by lucidguppy »

_RedPanda wrote: post #69

I agree that words like simply and just should not be used in documentations, but are people really getting upset about it? I couldn't imagine being this fragile

Learning tech through documentation is hard for some people.

People who try to make something easy by force of "magic words" is pretty common in the tech industry.

People who write the docs likely do not want the reader to feel stupid.

This is low hanging fruit and good advice. No one is screaming or fragile here.

Re: Just Simply – Stop saying how simple things are in our docs

#104

Post by warent »

smcl wrote: post #98
codeflo wrote: post #70

Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…

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"

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?

Re: Just Simply – Stop saying how simple things are in our docs

#105

Post by codeflo »

smcl wrote: post #98
codeflo wrote: post #70

Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…

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"

> 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.

Re: Just Simply – Stop saying how simple things are in our docs

#107

Post by seri4l »

dale_glass wrote: post #92

While we're here, could we also please have clear separation between commands and data? Eg, I hate stuff like: $ bin/rails generate scaffold user name email login Which is it? $ bin/rails --generate=scaffold --user=name --email=login Or: $ bin/rails --generate=scaffold --user=username --name=fullname --email=address --login=login_name Or: $ bin/rails --generate --scaffold=user --name=fullname --email=address --login=…

I'd say it's the last one, with a "subcommand based position dependant syntax" like git or zfs. It's a matter of taste but personally I prefer it to the traditional one. As long as the behavior is consistent remembering the order of the arguments is often easier than remembering the exact keywords.

Re: Just Simply – Stop saying how simple things are in our docs

#108

Post by nonethewiser »

smcl wrote: post #98
codeflo wrote: post #70

Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…

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"

> The post is about

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

Re: Just Simply – Stop saying how simple things are in our docs

#109

Post by throwawaaarrgh »

codeflo wrote: post #70

Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…

I could tell you you're missing the obvious answer, but that doesn't help you understand the thing you're missing. I could tell you the YouTube tutorial that starts from scratch has a very simple and obvious reason why it starts there, that a lot of other people get that you don't. But that doesn't help you either. And I could tell you that infantilizing someone who's having a hard time understanding something is the opposite of adult, but that doesn't tell you why.

Re: Just Simply – Stop saying how simple things are in our docs

#110

Post by warent »

nonethewiser wrote: post #108
smcl wrote: post #98

Earlier quoted context omitted.

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"

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

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"

Post reply on HN