One of the best pieces of advice I learned in high school from an incredible English teacher: when doing technical, avoid "-ly" words entirely. It has always been solid advice and has rarely led me astray.
[deleted]
Just Simply – Stop saying how simple things are in our docs
231–240 of 299 posts
Re: Just Simply – Stop saying how simple things are in our docs
#232Earlier quoted context omitted.
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 bounti…
connotation exists, you know
It does, generally. However you've failed to demonstrate such enough to remain on topic from what the article is actually saying and to what you posted. So much so I would assume you haven't read the article before you posted.
Re: Just Simply – Stop saying how simple things are in our docs
#233It'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:/…
> This should be automatized by writing tools. iA Writer¹ does it. It strikes out and greys out the words “simply” and “just” as part of its style check for fillers. ¹ https://ia.net/writer
The intro video for that app is one of the best I’ve seen in explaining quickly the value proposition of the software.
Many websites for software use so many buzzwords or marketing language as to not effectively communicate the value of the software.
Re: Just Simply – Stop saying how simple things are in our docs
#234It’s like when I was growing up, I always found it hilarious that the seller on TV touted a “low low price of ONLY xyz”, and they marveled at their own offer! As a kid, I realized that this is silly… it us the buyer who determines if the price is affordable or not. Most advertising in the last few decades just spouts nonsense in an effort to get you to buy something.
Not that the commercials were this deep, but the ability to afford something by the buyer doesn't change the relative pricing compared to the market. If I throw a 3 bedroom house on the market in a HCOL area for $200k when every similar home is going for $500k, it's a perfectly truthful statement to say it's being sold for a "low low price of only $200k". The fact that is out of the price range of a part time fast food worker is irrelevant. Though it's probably worth using "low low price of only" as a marker to investigate why something is so much cheaper than it's market price.
Re: Just Simply – Stop saying how simple things are in our docs
#235Not sure I've seen the sentence 'Setting this up is painfully simple.' used often in any documented instructions. It's unnecessary and rather arrogant.
Re: Just Simply – Stop saying how simple things are in our docs
#236This is a new rephrasing of an older mantra, which is to use fewer words when possible. The writings of the greats in our field exude this quality, for instance those of Dennis Ritchie. Mind you, he does use the aformentioned words, but they are often necessary, for instance, using the wording "simple shell" is true, because the shells he developed were indeed simpler than the ones before, and provably so.
The only twist in this new take is that it has an issue with commanding language using such words, and I agree. If you are telling me how to do something, there is no need to qualify the effort, because you don't have that information and neither do I, so the language ends up being verbose and, more crucially, incorrect.
Re: Just Simply – Stop saying how simple things are in our docs
#237Or 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…
First of all, you're exaggerating tremendously, as I don't see anybody "quitting their career" over documentation, and literally nobody is talking about impostor syndrome (in the article or comments here). You're seeing things that aren't there. But secondly, I think what you're writing is a great example of how their are two philosophies or ideologies of communication. One philosophy (that you seem to subscribe to)…
Nailed it.
You got me thinking with your "two ideologies"... I think it's more accurate to say, there are different modes of communication with different goals. At a minimum, there's sharing information, entertaining, social signalling, fighting/arguing. The relationship between speaker and listener varies in each case. Vocabulary, turn of phrase, tone all contribute. It's wise to figure out which case you're in and adjust accordingly.
Re: Just Simply – Stop saying how simple things are in our docs
#238As 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…
Saying "easily" can be beneficial because it signals to the students "See? This is really not that bad."
Many students think their grade is worse than it actually is, they think they're worse at math than they actually are or they think the course is harder than it really is
Re: Just Simply – Stop saying how simple things are in our docs
#239Earlier quoted context omitted.
connotation exists, you know
It does, generally. However you've failed to demonstrate such enough to remain on topic from what the article is actually saying and to what you posted. So much so I would assume you haven't read the article before you posted.
I read the article, you're refusing to see the forest through the trees.
Re: Just Simply – Stop saying how simple things are in our docs
#240Or 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…
The psychology involved in the response you're wondering about is really quite simple to understand.