Earlier quoted context omitted.
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 bounti…
Just Simply – Stop saying how simple things are in our docs
171–180 of 299 posts
Re: Just Simply – Stop saying how simple things are in our docs
#172It'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:/…
Re: Just Simply – Stop saying how simple things are in our docs
#173Or 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"
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.
Re: Just Simply – Stop saying how simple things are in our docs
#174Earlier quoted context omitted.
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
#175It'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:/…
Re: Just Simply – Stop saying how simple things are in our docs
#176Earlier 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”.
Re: Just Simply – Stop saying how simple things are in our docs
#177The author of this post appears to want to adopt the most infuriating traits of the MSDN documentation: namely, converting all documentation into a list of facts ("Mailers are another way to render a view", "a common use of mailers is…"). This is bad because if you are presented with a bare list of facts, you can't judge their relative importance, or how they relate to each other. The original Rails example was bad, but rather than fix it, they have rewritten it to make the badness more obvious.
The original was bad not because it uses the words "just" and "simply", but because it's verbose while still being hard to read. I still don't understand what the sentence starting "Due to this" is trying to say, and it's very unclear where they transition from giving general technical facts to walking through the specifics of the example. (It is certainly wrong to call something "painfully simple" - I can imagine maybe one or two places where it's ever appropriate - but it's not the main thing that is wrong with those docs.)
But the first two sentences of the original docs were easier to understand than the rewritten version. Compare:
> Mailers are really just another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they are just sending it out through the email protocols instead.
> Mailers are another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they send it out through email protocols instead.
I mean, is it rendering a view or isn't it?! The second version explicitly contradicts itself much more baldly than the first version, where the words "just" performed an important function by indicating that the sentence is about what is different between mailers and other renderers.
In the rewritten version, two of the three sentences of the first paragraph explicitly contradict each other, and the third is totally unrelated to what came before. This was a structural deficiency of the original docs, but removing the narrative elements of the text has amplified the problem to the point of absurdity.
Re: Just Simply – Stop saying how simple things are in our docs
#178Earlier quoted context omitted.
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
#179Earlier quoted context omitted.
I've known people who talk about their welding skill and would be unhappy if you pointed out their joint looked like crap. People, in general, are sensitive about anything important to them.
I was trying to compare equivalent professions across time periods, not to suggest that welders are any different than developers. I would not be surprised if modern day welders get offended by their equipment manual as well.
The difference is how people expressed those emotions or not, not whether they had them.
Re: Just Simply – Stop saying how simple things are in our docs
#180Or 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 whole feel good censorship feels no different from the old days, when my previous generation had to measure every single word, not that PIDE/DGS were going to be made aware of it.