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

151–160 of 299 posts

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

#151

Post by waboremo »

zemo wrote: post #125
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…

When you hire new people and they encounter this over and over again, onboarding drags on so, so much longer than it should, because people taking your position never think "we should reduce how complex this is", they think "they should stop being babies", and things just get progressively more obtuse and annoying and require more and more tribal knowledge instead of making sense. It's not the word "simply", it's tha…

This is literally a blog post about not using words like simply, not about reducing complexity or how to share knowledge across progress stages.

Some of us in this thread seem to be taking this blog post to project our past experiences onto, but this post is quite literally just about not using words like simply.

Also nobody will ever take the word literally from me, I will ensure all docs I come across use it bountifully!

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

#152

Post by KMnO4 »

sametmax wrote: post #14
flockonus wrote: post #9

Earlier quoted context omitted.

Not to jump on GPT hype too much, but a good idea perhaps for an addon targeting OSS, read over issues, PRs, scrub Stack Overflow and compile a descriptive list of the most common pitfalls for a certain lib. It's exactly the type of writing OSS authors don't like doing, and all the information is publicly available.

The problem is a lot of it is not publicly available. E.G: I asked chat gpt to help me install Python on Ubuntu 22.04, and it failed miserably. Why? Because 22.04 is recent and many pitfalls it comes with haven't been much documented yet. And it also don't know what is never written, but implicitly known if you deal with a lot of beginners. E.G: people get utterly confused with *args and **kwargs in Python, because i…

GPT != Chat GPT, GPT-4, etc.

It’s possibly to [“just simply”] train a GPT on whatever corpus you want.

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

#154

Post by adolph »

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…

> What happened to the expectation of people being adults?

The below quotes from Haidt summarize the concept that culture at large is promoting an inverse of CBT. As a result the knowledge increasing method of criticism has been hijacked by folx channeling their inner Foucault.

CBT (Cognitive Behavioral Therapy). In CBT you learn to recognize when your ruminations and automatic thinking patterns exemplify one or more of about a dozen “cognitive distortions,” such as catastrophizing, black-and-white thinking, fortune telling, or emotional reasoning.

. . .

Greg hypothesized that if colleges supported the use of these cognitive distortions, rather than teaching students skills of critical thinking (which is basically what CBT is), then this could cause students to become depressed. Greg feared that colleges were performing reverse CBT.

https://jonathanhaidt.substack.com/p/mental-health-liberal-g...

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

#155

Post by karmakaze »

The problem isn't the word "simple" it's words like "just". Within something complex, there can be a simple thread of reasoning that may not be easy to see and once communicated, everything takes shape and begins to make sense. That's worth communicating even if it's not easy to describe. Often that may be how the author came about the design. I wouldn't know how better to describe such a thing. Explaining all the complicated things that make the simple thing work ends up with the reader being able to agree with all the explanations, then wonder "yeah, but why do those all add up to do what it does?"

Tone of writing is important, but also a reader shouldn't assume that something that has a simple core is easy to make or later understand. I'd say it's more constructive to have your docs show how/why it's simple rather than make a statement and leave it up to the reader to piece it together.

What's a better word than "simple" that doesn't make it also imply "easy" to many? e.g. the elevator thought experiments of General Relativity are simple, but not easy to come up with or initially reconcile.

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

#156

Post by School-Cotton »

bvinc wrote: post #124
EdSharkey wrote: post #119

Earlier quoted context omitted.

It bothers me when someone good/bad naturedly corrects me on "blacklist" and encourages me to say "blocklist". I figure that stems from either overactive empathy or is a power play. Please continue to say "blacklist".

I see “blocklist” becoming more popular in programming. But it just occurred to me how bizarre and out of place it would be if the parent comment said “a blocklisted word”.

Plenty of people now say allowlist and denylist instead of whitelist and blacklist.

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

#157

Post by School-Cotton »

Fnoord wrote: post #91
Hendrikto wrote: post #22

Earlier quoted context omitted.

> avoid "-ly" words I hope this isn’t the actual advice you were given. They are called adverbs.

For non-native English speakers -ly is simpler than adverts. But simpler does not necessarily mean better long-term.

Why is it simpler? Are non-native English speakers less likely to know what an adverb is than English speakers are? I doubt it.

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

#158

Post by teddyh »

ekimekim wrote: post #114
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=…

The long-standing convention here, particularly for command line usage, is that: - String literals should be in lowercase (because by convention commands, argument names, etc should always be in all-lowercase, eg. "git cherry-pick" not "git cherryPick" or "git CHERRY-PICK") - Metavariables (stuff the user should fill in) should be in ALL-CAPS. - Not as strictly adhered to but still useful, [optional part] and {repeat…

> Metavariables (stuff the user should fill in) should be in ALL-CAPS.

If possible, (like it is here on HN), metavariables should be in ALL_CAPS_AND_ITALICS, because that’s how it’s done in Unix manual pages.

If italics is not available, it might be more clear to use the $SHELL_VARIABLE convention, depending on the audience.

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

#159

Post by qwery »

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…

It's not that the inclusion of this one word is offensive and so the entire product is ruined. It's a matter of accessibility. The more of it (accessibility) your thing has, the more accessible the thing is.

Why add something to your product that some users find makes their time with your product worse? If there is little to no reason[0] to include a feature and removing it could help some users, then not including it or removing it is a no-brainer.

> One month in,

If it took you a month, it sounds like it wasn't trivial. As presented, it sounds like your prof saying that was pointless at least.

[0] In this case, it's hard to see any benefit at all from adding the "simply ...".

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

#160

Post by furyofantares »

apricot wrote: post #123

As a math professor, I had an epiphany about the word "easily" several years ago. In my course notes, I used that word to mean "I guarantee you don't need any additional ideas here, just do the obvious thing." Nothing more was meant. But I realized that many students either didn't think the obvious thing was really that obvious, or maybe realized it but were reticent to follow that path because it invoved some tediou…

I read something a while ago that resonated, and I tried it out and have had a lot of success with my kid.

If the kid is hesitant to try something that you know will end up being easy, the natural thing is to tell them it's going to be easy.

But if you tell someone something is easy, and their personal experience is already that it's hard, well, the conclusion isn't necessarily "oh I was wrong, now it's easy, thanks dad, I'll actually try now". It may instead be "oh wow I suck at the easy thing I guess".

So now I do the opposite. She's struggling with something? I tell her it's hard. And I pair it with some indication that it won't be hard forever and is worth learning.

So now if I see her struggling I don't say "This is easy, let me show you". I definitely don't say "This is easy, just give it a shot".

I say "Oh yeah, this part's hard at first. But I know a trick."

Post reply on HN