This is
really annoying
to read
on my
relatively small
phone screen.
There is
way too
much whitespace
and only
about 4
words per
line.
Just Simply – Stop saying how simple things are in our docs
21–30 of 299 posts
Re: Just Simply – Stop saying how simple things are in our docs
#22One 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.
Re: Just Simply – Stop saying how simple things are in our docs
#23+1 to the article. I’ve noticed this more recently. Ironically, it seems to be more common with coding communities known for their welcoming spirit and helpful nature, for example Rust. Gratuitous repetition of how easy something is can make it feel harder when understanding is not immediate.
I think it's more common in technical communities trying desperately to persuade people that their obscure low-level tech is not as obscure and low-level as it actually is -- for example Rust (but also Linux, C/C++, BSDs, networking, etc).
The post is right: if you're explaining something, it's because the other person could not understand it without help, which means it's not, in fact, easy. It might be easy to repeatedly use it once you understand it, but it's not easy to grasp in the first place - otherwise you wouldn't have to be there in the first place.
Re: Just Simply – Stop saying how simple things are in our docs
#24...unless it's actually simple. Unfortunately a lot of software these days (especially the "modern" stuff) does not qualify.
Re: Just Simply – Stop saying how simple things are in our docs
#25It’s like when I was growing up, I always found it hilarious that the seller on TV touted a “low low price of ONLY xyz”, and they marveled at their own offer! As a kid, I realized that this is silly… it us the buyer who determines if the price is affordable or not. Most advertising in the last few decades just spouts nonsense in an effort to get you to buy something.
Re: Just Simply – Stop saying how simple things are in our docs
#26One 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.
This is a rule in the Hemingway app: https://hemingwayapp.com/
Re: Just Simply – Stop saying how simple things are in our docs
#27Earlier quoted context omitted.
Like "otherwordly", obviously. Never use "otherwordly" ph'nglui technical documentation, ngnah ymg' risk s̵͖͕͓̒̾̾ǘ̵̢̺͓͊́m̵̟͙̓̒̚m̴͉̠͖̈́͊͠o̸̞̺̻̾́̀n̵͖̻͓̓̔i̴̢͚͕̿̕͝n̴͇̞͎͒̀̚g̵̢̟͙̾̚͝ z̴̪̠̟̾̿͘a̸͇̞͙̔͌͛l̵̢̟̘͆̒g̴͓͔̀́̿ö̵̪̠́͑̓.̴̢͙̪́͝͠
It was a joke, obviously. They're called adverbs.
Unlike mine, obviously. I'm very serious.
Re: Just Simply – Stop saying how simple things are in our docs
#28Did this article really deserve its own domain?
Re: Just Simply – Stop saying how simple things are in our docs
#29This is absolutely true. It irritates me to no end when I read something that goes "oh, flooricating is so easy, you just scombobulate the foolarizer with bardotic parameters like this: ". No, dude, it's not easy: if it were, we wouldn't be here - most people don't like to read manuals or even ask for help, if they can avoid it.
Re: Just Simply – Stop saying how simple things are in our docs
#30[This library] makes it even harder to [do difficult thing] I will suffer you through it, at the end you will hate me, be more confused and have even less of an idea how to use [this library]
[Complicated thing] made more complicated and harder.
I will have you do many difficult things and remember them just to do [difficult thing].
Good luck, you are going to need it!