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

51–60 of 299 posts

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

#51

Post by sjrd »

kqr wrote: post #13
sametmax wrote: 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:/…

I remember reading one of those and it made a huge impression on me. I've followed it ever since and taught others to do the same. As far as I can tell, it has only been met with appreciation. That said, sometimes I find myself trying to write around "simple" when I really mean "less complex", and I have to remind myself that what I really want to avoid is implying "easy", not "relatively less complex".

You can use comparatives, like "simpler", usually without issues. Something can be simpler than something else without necessarily being simple. Superlatives like "simplest" can sometimes be used as well. After all, being the simplest thing means to be simpler than all the other things; still not necessarily simple.

It's only the positive form "simple" which is problematic and should be almost always avoided.

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

#52

Post by alpaca128 »

userbinator wrote: post #24

...unless it's actually simple. Unfortunately a lot of software these days (especially the "modern" stuff) does not qualify.

Yes, often it's used for things where you "simply" have to install a dependency which does so much stuff its official website can't tell you what it is, then you have to figure out how to install precisely version 3.9.7 because another one won't work for this, and of course use that one workaround to initialize it the first time, and you're set unless one of the 10 git clones in some script fails.

Many things could instead be as simple as "python main.py".

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

#54

Post by kqr »

sjrd wrote: post #51
kqr wrote: post #13

Earlier quoted context omitted.

I remember reading one of those and it made a huge impression on me. I've followed it ever since and taught others to do the same. As far as I can tell, it has only been met with appreciation. That said, sometimes I find myself trying to write around "simple" when I really mean "less complex", and I have to remind myself that what I really want to avoid is implying "easy", not "relatively less complex".

You can use comparatives, like "simpler", usually without issues. Something can be simpler than something else without necessarily being simple. Superlatives like "simplest" can sometimes be used as well. After all, being the simplest thing means to be simpler than all the other things; still not necessarily simple. It's only the positive form "simple" which is problematic and should be almost always avoided.

This is indeed where I usually go. "Under condition X, it is simpler to Y" rather than "Under condition X, you can simply Y."

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

#55

Post by fnordsensei »

WastingMyTime89 wrote: post #48
sametmax wrote: 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:/…

"Simply" when used in the sense of "without addition, alone" is perfectly fine. I find the issue people have is not really with the word simply but with bad documentation and badly designed tools. That’s not going to be fixed by avoiding one word.

“Simple” vs “easy”: https://youtu.be/LKtk3HCgTa8

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

#57

Post by paradox242 »

I get this a lot while reading about something new which I have heard might solve my problem, or while better trying to understand a system already in place. The documentation begins with a comforting high level description that is vague enough to sound like it might fit my use case, but then abruptly transitions into a table of contents listing the minutiae of interfaces, API calls, system components, without giving a suitable intermediary description of how any of these things might work in concert to actually solve the problem. This is left as an exercise to the reader.

You will almost never be offered any central insight from the author(s) about their mental framework for the system they have designed, or even that of the problem that it is intended to solve (so that you might more quickly determine whether your particular problem is a member of this class). Instead, I will often find this missing information presented in a random blog of some individual who, having won this knowledge through heroic effort, is determined to provide the context that they would have wished to find themselves upon first starting their journey.

Why does it have to be this difficult?

I suspect a lot of this has to do with the organization of companies involved (Google and Microsoft are some of the worst offenders here) in that the people writing the documentation are often not the people creating the systems, and so don't really understanding anything they are describing themselves. Meanwhile, those that designed the system suffer from the Curse of Expertise where their familiarity blinds them to things that are "obvious" to them, but are not actually inherent to the system they have designed. They are ignorant of all of the background understanding and experience that lead them to design the system or approach the problem in a particular way, when this is actually the most valuable thing I look for in any documentation I read.

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

#58

Post by latexr »

sametmax wrote: 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:/…

> 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

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

#59

Post by kstenerud »

Reminds me of the turbo encabulator presentation [1].

Quote: "The latter consisted simply of six hydrocoptic marzlevanes, so fitted to the ambifacient lunar waneshaft that side fumbling was effectively prevented."

[1] https://www.youtube.com/watch?v=Ac7G7xOG2Ag

Post reply on HN