Earlier quoted context omitted.
What, like "butterfly"?
Avoiding "butterfly" when writing technical documentation sounds like a good advice.
The keyboard in your thinkpad 701C has a mechanism we affectionately call butter… oh never mind.
Just Simply – Stop saying how simple things are in our docs
41–50 of 299 posts
Re: Just Simply – Stop saying how simple things are in our docs
#42Did this article really deserve its own domain?
Indubitably.
Re: Just Simply – Stop saying how simple things are in our docs
#43It'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:/…
it's not only the word `simply`; I find myself perusing more and more docs that boil down to an emoji-laden slab of super-shallow tutorials and marketing lingo, which just tell you how to do the most basic thing - or the barely less basic thing in the most ideal scenario - and nothing more.
I'm all ok with tutorials and examples into the docs, but give some depth to them, not only breadth (or emojis).
Re: Just Simply – Stop saying how simple things are in our docs
#44Did this article really deserve its own domain?
one down [checks account on dnsimple.com] 59 to go...
Re: Just Simply – Stop saying how simple things are in our docs
#45It'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.
True, there is no such thing as a concept been obvious to everybody.
Feyman has this great bit in his biography where he tackles mathematicians that keep saying in their demonstration that a step is trivial.
Re: Just Simply – Stop saying how simple things are in our docs
#46Personally 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 docume…
> If you have issues with that simple task, maybe you are doing it wrong and should ask for help.
Far more common, in my experience, is that the author considered it so simple they did not spend any effort explaining it adequately. I.e. they were so distanced from their target audience (by virtue of their amassed experience) that they forget to adapt the text for them.
There are other, more descriptive ways to explain that things are more or less complex for experienced users.
Re: Just Simply – Stop saying how simple things are in our docs
#47Super frustrating. There’s a lot of “just do x” in stack overflow answers as well. It “just” makes the reader feel stupid.
Big agree, everytime I find myself typing a comment on slack along the lines of "can we just do x", I immediately stop and delete the word just. The message doesn't loose any meaning and is a lot less obnoxious.
Re: Just Simply – Stop saying how simple things are in our docs
#48It'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.
Re: Just Simply – Stop saying how simple things are in our docs
#49Earlier quoted context omitted.
> 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?
In English, the math jargon term “simplifies to” means roughly “is equivalent to this less complex form”. It does not connote difficulty.
Re: Just Simply – Stop saying how simple things are in our docs
#50Did this article really deserve its own domain?
People can get domains for whatever they want, you don't need to earn them.