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

251–260 of 299 posts

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

#251

Post by lallysingh »

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…

"Simple" reads "simple for me" (the author). That can be really frustrating at times.

But the real sin here is wasting words on useless bullshit. Just get to the damned point. "Just simply" is 100% waste. I can replace "Just simply verb" with "verb" and the sentence is already better, without putting a bunch of emotional loading into the context of the discussion.

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

#252

Post by Tade0 »

javajosh wrote: post #134
ellisv wrote: post #132

Earlier quoted context omitted.

Whenever my professor said "it's easy to show" and then moved on it felt very hand wavy. The steps weren't obvious to me and didn't become more obvious as the course went on because no one taught me how to think of the "obvious" thing.

The worst situation in my college experience was when a prof would go over some mundane part of a proof in excruciating detail, and then hand-wave the important part. I realized later in life it was because they prof didn't understand it, either.

I had a similar situation after a "last chance" exam for one course.

The lecturer was unavailable, so he assigned a substitute to grade the exam. There was a problem there similar to the casting problem (assuming each subsequent candidate has probability P to be better than the previous one, when should we make our pick), only the probabilities were different each time - this wasn't covered in the course material. I deconstructed it by calculating all the probabilities by hand, because I didn't know any other way.

The substitute asked me to come by and explain how I solved it, because apparently I was the only one to do so.

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

#253

Post by pclmulqdq »

tetha wrote: post #202
bityard wrote: post #194

Earlier quoted context omitted.

Believe me, I am all for people having thicker skins and less entitlement overall. I believe offense is generally taken rather than given, and social media's culture of constant outrage over some thing or another is a form of intellectual and moral decay. HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They…

> HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They tend towards considering only what they want the reader to do or think, not necessarily who the reader might be or what _they_ want to get out of the writing. In my experience - and as a problem on top - writing seems to be one of these crafts in which…

Another way to put this advice on how to write with precision is: carefully consider any use of an adverb in formal writing (pun intended). Most adverbs in formal writing can be replaced by using a better adjective or verb. For some reason, adverbs like "simply" and "quickly" make people feel bad when the process isn't simple or quick, but using words like "straightforward" does not.

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

#254

Post by johnchristopher »

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…

> Similarly, when documentation mentions to "simply" do something, and I don't get it, isn't that a clear hint that I'm still missing a concept somewhere and need to look around for an explanation?

Nah, it's fluff. Write good technical documentation, not your wishy-washy feelings about how easy or hard it is.

edit: write like you'd write an RFC.

> Or maybe -- controversial opinion here -- people shouldn't be such babies.

Seriously, why is the introduction of the top comment a thinly veiled insult disguised as a weak rhetorical device ?

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

#257

Post by jstummbillig »

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…

Resilience and good communication don't share an axis. You can want and have both. To me, the examples in the article make a convincing case for what's stronger writing and that's good enough.

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

#258

Post by tomcam »

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 like your perspective in general. The reason I don’t mind getting a little bit worked up about it is because most documentation is terrible and that can make people frustrated and feel bad when it doesn’t have to. Which plays into your point, but spreading this over thousands, or millions of users seems like a terribly unproductive strategy. If you correct the documentation, once you will make many people's experience better over the life of the documentation.

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

#259

Post by savanaly »

tomcam wrote: post #255

While we’re at it, let’s stop saying “add additional“. “Add” means the same thing

"Add milk to that cereal" vs "Add additional milk to that cereal"

If that was all I heard of a conversation from the other room, I would form two different ideas of what was going on in that room, hence they can't mean the same thing.

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

#260

Post by ozim »

lallysingh wrote: post #251
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…

"Simple" reads "simple for me" (the author). That can be really frustrating at times. But the real sin here is wasting words on useless bullshit. Just get to the damned point. "Just simply" is 100% waste. I can replace "Just simply verb" with "verb" and the sentence is already better, without putting a bunch of emotional loading into the context of the discussion.

Part of article about "sharing excitement" I would rewrite:

Stop writing "it is easy - just do x" because it is plain marketing bullshit that people are compelled to add to documentation or website describing library/tool only for a reason that - they think they should do it.

Post reply on HN