Now that I've written a few specifications (which tend to have a much higher explanatory burden), I've come to appreciate just how difficult it is to write introductory material to a subject that you're an expert in. Like any skill, it takes a lot of practice.
Just Simply – Stop saying how simple things are in our docs
61–70 of 299 posts
Re: Just Simply – Stop saying how simple things are in our docs
#62...unless it's actually simple. Unfortunately a lot of software these days (especially the "modern" stuff) does not qualify.
It’s very difficult to tell what is actually simple
Re: Just Simply – Stop saying how simple things are in our docs
#63please add "blazing fast" to this list
Rock star ninja rocket emoji Rick and Morty gif
Re: Just Simply – Stop saying how simple things are in our docs
#64It’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.
They use it because it works on people with IQs that are average or below, even adults
Re: Just Simply – Stop saying how simple things are in our docs
#65One 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.
> when doing technical, avoid "-ly" words entirely.
Following its own advice, “entirely” can be cut without loss of meaning. Considering the replies you’re getting, perhaps a better way to phrase it in the future would be:
> eschew "-ly" adverbs.
That way it’s clear you’re referring to a specific subset of adverbs.
Re: Just Simply – Stop saying how simple things are in our docs
#66Earlier quoted context omitted.
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
#67Earlier quoted context omitted.
Not to jump on GPT hype too much, but a good idea perhaps for an addon targeting OSS, read over issues, PRs, scrub Stack Overflow and compile a descriptive list of the most common pitfalls for a certain lib. It's exactly the type of writing OSS authors don't like doing, and all the information is publicly available.
The problem is a lot of it is not publicly available. E.G: I asked chat gpt to help me install Python on Ubuntu 22.04, and it failed miserably. Why? Because 22.04 is recent and many pitfalls it comes with haven't been much documented yet. And it also don't know what is never written, but implicitly known if you deal with a lot of beginners. E.G: people get utterly confused with *args and **kwargs in Python, because i…
There's an explicit caveat on chat gpt: limited knowledge of the world and events after 2021. You're asking about 22.04.
Re: Just Simply – Stop saying how simple things are in our docs
#68I like that the example is talking exactly about Rails Mailer. I've used it once and it was really painful to setup, which is exactly the post point. Love it.
Re: Just Simply – Stop saying how simple things are in our docs
#69I agree that words like simply and just should not be used in documentations, but are people really getting upset about it? I couldn't imagine being this fragile
Re: Just Simply – Stop saying how simple things are in our docs
#70Or 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 special clever trick was required to make the deduction, just a lot of perseverance.
Similarly, when documentation mentions to "simply" do something, and I don't get it, isn't that a clear hint that I'm still missing a concept somewhere and need to look around for an explanation?
What I wonder is: Why is this so personal? Are people really shamed into quitting their career over a misplaced "simply" in a piece of tech writing because it triggers their impostor syndrome? Is that the reason why tech documentation has slowly been evolving into 50-minute step-by-step YouTube tutorials that start with installing the IDE? What happened to the expectation of people being adults?