This is just yet another politeness law, adding some more words we shouldn't use. There is a useful message though: make writing clear and unadorned.
Just Simply – Stop saying how simple things are in our docs
71–80 of 299 posts
Re: Just Simply – Stop saying how simple things are in our docs
#72This is just yet another politeness law, adding some more words we shouldn't use. There is a useful message though: make writing clear and unadorned.
> There is a useful message though: make writing clear and unadorned
I think this is the key takeaway. From the example in the article, phrases like 'just', 'painfully simple', 'just another way' aren't instructive nor objective, but decorative and subjective.
Documentation should have exactly one purpose: to instruct. There ought to be no mentions of difficulty, or obviousness, or triviality, or any other smart-aleck commentary. It ought to have a direct, clear tone, such as 'do X, which causes Y. Now do A and B, which requires C.' and so on.
Re: Just Simply – Stop saying how simple things are in our docs
#73Or 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 s…
It’s because “simply” became a marketing tool, devoid of substance. It’s not simple because it objectively is, it’s because we say so in every other sentence so that you cannot decouple the notion of our product from the word “simple” anymore. It must be simple, because you have been indoctrinated.
It’s noise not unlike those 1-hour long “Shopping TV” ads.
I’m not against using the word as ling as it’s put into some kind of framework which allows some actual assessment of these claims:
— Simple compared to what?
— What prior knowledge or skill is assumed?
— When does it stop being simple?
But since “simple” is being either used by authors deeply enamored with their brainchild, or as I said above, as a marketing (read: manipulation) tool, your chances of getting straight answerd are slim.
Re: Just Simply – Stop saying how simple things are in our docs
#74Re: Just Simply – Stop saying how simple things are in our docs
#75Earlier quoted context omitted.
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/…
I think that the advice is a bit more nuanced, your first example is fine as it is but consider the variants:
"...that are clearly always available."
"...that are obviously available."
"...that are simply available."
These adverbs are not only redundant but their presence suggest that things are actually not clear, simple or obvious.
Re: Just Simply – Stop saying how simple things are in our docs
#76> If someone’s having to read your docs, it’s not “simple”
The opening quote of the article is so stupid. If the docs are enough to teach you to use a tool, that seems quite simple to me.
Re: Just Simply – Stop saying how simple things are in our docs
#77This is just yet another politeness law, adding some more words we shouldn't use. There is a useful message though: make writing clear and unadorned.
I see it differently. If you are writing documentation for a system you know a lot about, things are completely simple for you right then right there. But as we all know in 6 months you'll look at your own code and think "who the ... wrote this?".
So avoiding the word "simple" isn't about accommodating the 5% of your least intelligent users and dumbing down the content, but the > 90% who are not so into the topic as you are right now.
Re: Just Simply – Stop saying how simple things are in our docs
#78[dead]
Re: Just Simply – Stop saying how simple things are in our docs
#79Or 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 s…
I agree with your point. Nowadays, people seem to be overly sensitive about their code and the way we communicate, among other things.
It's important to remember that the code is not a reflection of ourselves, and not everyone will be pleased with it. Some will provide good guidance, while others will not. Therefore, we should remove our ego from the code. Code is like a lollipop that we enjoy, but then discard once we're done with it.
If I don't understand a design doc, it doesn't necessarily mean that I'm stupid or that the writer is bad at communicating. It may simply require more effort on my part to fully comprehend it.
I don't understand why some people are so sensitive and take everything as a personal attack.
Re: Just Simply – Stop saying how simple things are in our docs
#80I don't entirely disagree with the sentiment, but the example is so contrived. The problem with these sentences isn't that the word "just" and "simply" are somehow upsetting to the reader but that they're clumsy sentences.
"Mailers are really just another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they are just sending it out through the email protocols instead. Due to this, it makes sense to just have your controller tell the Mailer to send an email when a user is successfully created.
Setting this up is painfully simple."
That said, I think there's rarely a good reason to say something is "simple" in documentation. Explain how to do it and let the user decide if it's simple.