Just Simply – Stop saying how simple things are in our docs • Hacker News Board

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

#31

Post by wouldbecouldbe » Sun, Apr 30, 2023, 9:19 AM UTC

Wording is one thing, but what is always annoying moving to a new library or language is the tacit knowledge the docs assume.

It's a fine line, one can assumes a certain knowledge to even be functional, but in doubt I think it's better to be extra verbose.

Few examples: - JS libraries not showing how to import the modules used in code examples. - Everything in the kubernetes docs - In Xcode explanations often it just mentioned: go the "build settings", etc. In beginning it's extremely confusing to find anything in that program.

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

#32

Post by junon » Sun, Apr 30, 2023, 9:23 AM UTC

Hendrikto wrote: post #22

junon wrote: post #2

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.

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

It was the exact advice given. Not all adverbs end in "-ly", either, and not all adverbs should be avoided in technical writing; that'd be impossible.

The rule states "-ly" words because those words are often cruft or crutch words that can be removed. If the sentence can't stand on its own without that word, then the sentence probably doesn't belong in the body of technical writing.

Compare this with time-related adverbs, which generally provide chronological structure. Those are more relevant for technical writing.

So yes, avoid "-ly" words. Not adverbs in general. That was the advice given.

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

#33

Post by imiric » Sun, Apr 30, 2023, 9:34 AM UTC

I agree with the article, but to be fair, all software aims to simplify a task. So calling a procedure "simple" is usually done in comparison with what used to be more difficult/complicated.

Though my biggest annoyance with this is when it's part of network protocol names: SNMP, SMTP, TFTP, etc. What you usually find when working with these is that they're far from being simple, so it borders on false advertising. Maybe they start that way, and that is the author's vision, but when they mature it often stops being true. Or maybe they were simple compared to what predated them, and for their time and place. But it's still a bad idea to name a protocol or standard that.

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

#34

Post by rikschennink » Sun, Apr 30, 2023, 9:36 AM UTC

Super frustrating.

There’s a lot of “just do x” in stack overflow answers as well.

It “just” makes the reader feel stupid.

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

#35

Post by BossingAround » Sun, Apr 30, 2023, 9:39 AM UTC

imiric wrote: post #33

I agree with the article, but to be fair, all software aims to simplify a task. So calling a procedure "simple" is usually done in comparison with what used to be more difficult/complicated. Though my biggest annoyance with this is when it's part of network protocol names: SNMP, SMTP, TFTP, etc. What you usually find when working with these is that they're far from being simple, so it borders on false advertising. Ma…

> I agree with the article, but to be fair, all software aims to simplify a task. So calling a procedure "simple" is usually done in comparison with what used to be more difficult/complicated.

It follows that calling anything "simple" is redundant. Either it's implied (i.e. "of course it should be simple, otherwise I'd just use X"), or it's wrong. Indicating the difficulty of anything has no place in any technical text.

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

#36

Post by rzzzt » Sun, Apr 30, 2023, 9:42 AM UTC

stavros wrote: post #8

junon wrote: post #2

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.

What, like "butterfly"?

Avoiding "butterfly" when writing technical documentation sounds like a good advice.

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

#37

Post by nohuck13 » Sun, Apr 30, 2023, 9:44 AM UTC

junon wrote: post #32

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.

It was the exact advice given. Not all adverbs end in "-ly", either, and not all adverbs should be avoided in technical writing; that'd be impossible. The rule states "-ly" words because those words are often cruft or crutch words that can be removed. If the sentence can't stand on its own without that word, then the sentence probably doesn't belong in the body of technical writing. Compare this with time-related adv…

Some adverbs not ending in "-ly" are always, soon, today, ever, yet.

"The Python interpreter has a number of functions and types built into it that are always available." [1]

"Long option values can be split across multiple lines simply by indenting the continuation lines." [2]

Agree with your teacher in that the first one seems fine. [1] https://docs.python.org/3/library/functions.html

[2] https://docs.python.org/3/distutils/configfile.html

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

#38

Post by wdfx » Sun, Apr 30, 2023, 9:52 AM UTC

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

Similarly, one should never state that something is "obvious".

I catch myself sometimes starting a sentence with "Obviously," and usually stop myself at that point and restart.

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

#39

Post by kazinator » Sun, Apr 30, 2023, 9:53 AM UTC

BossingAround wrote: post #35

imiric wrote: post #33

I agree with the article, but to be fair, all software aims to simplify a task. So calling a procedure "simple" is usually done in comparison with what used to be more difficult/complicated. Though my biggest annoyance with this is when it's part of network protocol names: SNMP, SMTP, TFTP, etc. What you usually find when working with these is that they're far from being simple, so it borders on false advertising. Ma…

> I agree with the article, but to be fair, all software aims to simplify a task. So calling a procedure "simple" is usually done in comparison with what used to be more difficult/complicated. It follows that calling anything "simple" is redundant. Either it's implied (i.e. "of course it should be simple, otherwise I'd just use X"), or it's wrong. Indicating the difficulty of anything has no place in any technical te…

So, it's off limits in a technical text to say that, say !(!a && !b) simplifies to a || b, or anything else in a similar vein?

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

#40

Post by TrianguloY » Sun, Apr 30, 2023, 9:53 AM UTC

Personally I prefer that type of sentences, it allows me to know which procedures are easy once you know them, and which aren't.

If you are new, everything is difficult. But if you read that something is simple you know that, even though for you right now it isn't, it will be in the future.

If you have issues with that simple task, maybe you are doing it wrong and should ask for help. On the other hand, if the documentation says that something is hard, you shouldn't even attempt it as a beginner, and perhaps wait until you have more experience.