Live data from Hacker News

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

justsimply.dev

171–180 of 299 posts

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

#171
post #125

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…

connotation exists, you know

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

#172
post #3

It'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:/…

Monty Python’s sketch “How to Do It” has some decades.

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

#173
post #98
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…

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"

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

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

#174
post #91

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

In their own language they know it but uncommon words in a non-native language might have to be looked up. Its theoretical vs practical.

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

#175
post #3

It'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:/…

In the case of documentation provided by the creators of the software, there's a more substantial vexation: Use of such words comes off as vacuous, self-praising bullshit.

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

#176
post #124

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

Blocklist for me is a list of blocks, like the one you gather with badblocks(8) and then pass to fsck(8).

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

#177
I'm surprised nobody has pointed out yet that "Mailers are another way to render a view" has lost information that was present in "Mailers are really just another way to render a view.".

The 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

#178
post #124

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

Goodlist and ungoodlist.

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

#179
post #162

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

I A. Don't see significant similarity between welding and programming B. Think that you would be wrong about people being annoyed about things that make their work harder across any time period.

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

#180
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 am on the same page, for whatever reason everyone is fragile now, and we need to make all efforts to avoid breaking things into thousands of broken glass pieces.

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.

Post reply on HN