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

Re:Just Simply – Stop saying how simple things are in our docs by smcl on Sunday April 30, 2023 @08:18AM (#35761882)

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"

[ Parent | on HN ]

Re:Just Simply – Stop saying how simple things are in our docs by codeflo on Sunday April 30, 2023 @08:40AM (#35762007)

> 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, it's advice for people who write for people who act offended when reading "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 obviously 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.

[ Parent | on HN ]

Re:Just Simply – Stop saying how simple things are in our docs by zabzonk on Sunday April 30, 2023 @08:59AM (#35762134)

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.

[ Parent | on HN ]

Re:Just Simply – Stop saying how simple things are in our docs by lowercased on Sunday April 30, 2023 @11:35AM (#35763537)

* He used 'trivialities' in a song.

* "(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?

[ Parent | on HN ]

Re:Just Simply – Stop saying how simple things are in our docs by whstl on Sunday April 30, 2023 @11:37AM (#35763559)

Yep.

And paraphrasing: Imagine there's no absolutes. It's easy if you try.

[ Parent | on HN ]

Re:Just Simply – Stop saying how simple things are in our docs by zabzonk on Sunday April 30, 2023 @11:47AM (#35763675)

> 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

[ Parent | on HN ]

Re:Just Simply – Stop saying how simple things are in our docs by lowercased on Monday May 01, 2023 @10:16AM (#35773084)

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.

[ Parent | on HN ]

Re:Just Simply – Stop saying how simple things are in our docs by warent on Sunday April 30, 2023 @08:36AM (#35761980)

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 or keyboard with a better handle, 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?

[ Parent | on HN ]

Re:Just Simply – Stop saying how simple things are in our docs by nonethewiser on Sunday April 30, 2023 @08:44AM (#35762038)

> The post is about

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

[ Parent | on HN ]

Re:Just Simply – Stop saying how simple things are in our docs by warent on Sunday April 30, 2023 @08:47AM (#35762059)

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"

[ Parent | on HN ]

Re:Just Simply – Stop saying how simple things are in our docs by cal85 on Sunday April 30, 2023 @09:21AM (#35762291)

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.

[ Parent | on HN ]

Re:Just Simply – Stop saying how simple things are in our docs by avereveard on Sunday April 30, 2023 @11:14AM (#35763298)

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

[ Parent | on HN ]