Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

justsimply.dev

Post reply on HN
Print view View original

201–210 of 299 posts

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

#201

Post by hooverd »

tremon wrote: post #128
TrianguloY wrote: post #40

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 docume…

and should ask for help By... reading the documentation, for example?

Simply find the relevant thread in the mailing list. Or just watch one of the author's talks.

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

#202

Post by tetha »

bityard wrote: post #194
codeflo wrote: post #70

Or 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…

Believe me, I am all for people having thicker skins and less entitlement overall. I believe offense is generally taken rather than given, and social media's culture of constant outrage over some thing or another is a form of intellectual and moral decay. HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They…

> HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They tend towards considering only what they want the reader to do or think, not necessarily who the reader might be or what _they_ want to get out of the writing.

In my experience - and as a problem on top - writing seems to be one of these crafts in which experience accrues slowly and usually only with good readers.

For example, I've removed "just simply" from my usual documentation vocabulary by just simply following a few steps - sorry, that was too tempting to leave out :) But one realization that drove me away from "simply" was: Simply usually is an imprecise word and this lack of precision opens up doors for misunderstanding. Often when I used simple, I meant it as "simple process" vs "convoluted process". In those cases, I replaced it with "straight-forward" or similar words. This is intended for the reader to judge if they are getting into a process you can just do during a boring meeting, or if they are about to enter some escher-esque rabbit hole.

However, this realization was mostly driven by good readers who informed me about possible misinterpretations my choice of words offers to them. So, even if it sounds nit-picky, go ahead and point out such things and start looking for those. It'll make you a better writer, and other writers around you better.

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

#203

Post by Kye »

tetha wrote: post #202
bityard wrote: post #194

Earlier quoted context omitted.

Believe me, I am all for people having thicker skins and less entitlement overall. I believe offense is generally taken rather than given, and social media's culture of constant outrage over some thing or another is a form of intellectual and moral decay. HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They…

> HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They tend towards considering only what they want the reader to do or think, not necessarily who the reader might be or what _they_ want to get out of the writing. In my experience - and as a problem on top - writing seems to be one of these crafts in which…

The best thing I ever did for my writing was subject it to editors and beta readers. It can be hard to find friends who are willing to pick your writing apart, but they're the best kind.

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

#204

Post by wongarsu »

Fnoord wrote: post #89
wdfx wrote: post #38

Earlier quoted context omitted.

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.

Clearly, there are other words which sound condescending. Reading text (documentation, for example) is more enjoyable when it inspires one's curiosity instead of belittling them on things which are simple, easy, obvious, clear, etc. Although humor helps, makes it stick.

> Clearly, there are other words which sound condescending.

Well played. You start with a synonym for obviously, but pointing that out just proves your point.

Maybe there are some sentences that can justifiably start with obviously, clearly, etc after all

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

#205

Post by crazygringo »

codeflo wrote: post #70

Or 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…

First of all, you're exaggerating tremendously, as I don't see anybody "quitting their career" over documentation, and literally nobody is talking about impostor syndrome (in the article or comments here). You're seeing things that aren't there.

But secondly, I think what you're writing is a great example of how their are two philosophies or ideologies of communication.

One philosophy (that you seem to subscribe to) is that it's the prerogative of the speaker (writer) to communicate however they think is right, and it's the responsibility of the listener (reader) to do the work to understand it, and reponsibility for miscommunication lies with the listener. To use your words, the speaker doesn't need to "baby" the listener, and the listener is wrong to be "personally offended".

But the other philosophy is that it's the responsibility of the speaker to communicate in a way that will be best understood, and it's the prerogative of the listener to note where the speaker's communication is unclear, misleading, frustrating, or offensive to the listener. It's the speaker's job to make a good faith effort to know their audience and communicate appropriately for that audience, and to apologize and rephrase when they make mistakes.

Now, which one is right? Well, there is no "right". What there is is -- which one serves you better as the speaker? Which philosophy will further your goals, which one will get you further in life?

Well if your goal is to be able to get angry at listeners/readers who don't get it and feel smarter than others, by all means adopt the first philosophy. But if your goal is for your speech and writing to have the impact you want it to have, the second philosophy is going to be more productive for you. And calling people "babies" is about as counterproductive as you can be in terms of getting people to listen to you.

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

#206

Post by lnxg33k1 »

ho_schi wrote: post #182

Germans here? Klicken sie einfach auf “Ausführen”. Click simply on “Execute”. The writers of manuals love the word “simply”. There is just one problem: If you need instructions it is NOT simple for your users. The word doesn’t add info. The text to comprehend becomes longer. And the task even harder for readers. I started using “einfach” too much and now delete it whenever appropriate.

I mean sometimes things are simple, and are put in docs because someone doesn't get what's obvious, I had to sometimes to shut myself from offending people who were stuck on screens that were so obvious and instead of trying and fail or google, waited for the help of someone to unstuck them, docs exist with simple things inside and that is not enough to measure if those things are simple or not, they also exist like if that one guy who couldn't understand the obvious and had to ask, does a doc that documents something that was understood without it by 999 people, make what is documented unclear because of 1 that couldn't see?

if you go to a place where you see a sign "Don't touch the fire", does it make not touching the fire not obvious because the sign exist? Or we have to put obvious sign for those who aren't cerebrally developed enough to understand it without the sign?

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

#207

Post by jodrellblank »

shri_krishna wrote: post #143
codeflo wrote: post #70

Or 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…

[flagged]

The left: "X change would be better because Y".

The right, having a meltdown about it: "I'm superior, you're snowflakes, you're pathetic babies, you're weak, I'm a real adult, I'm not afraid, you're triggered by everything, blah blah".

Why does this happen? Why are you so insecure that suggesting a way for documentation to be made clearer makes you conjour up a fantasy about an imaginary group of people who can't learn Russian so that proves they're inferior to you?

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

#208

Post by civilized »

codeflo wrote: post #70

Or 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…

For those that don't find the irritation caused to others as a sufficient reason to stop doing it, consider that it just simply sounds unprofessional and basically just simply inhibits clarity. It sounds like a slightly more refined version of spamming, like, the filler word "like" all over your documentation.

People rightly deduct style and professionalism points for this regardless of whether they're personally offended.

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

#209

Post by grog454 »

bityard wrote: post #194
codeflo wrote: post #70

Or 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…

Believe me, I am all for people having thicker skins and less entitlement overall. I believe offense is generally taken rather than given, and social media's culture of constant outrage over some thing or another is a form of intellectual and moral decay. HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They…

I agree in general that they're often misused, but "just" and "simply" do have a place. Specifically in place of "only" or "instead", or to set up a subjective comparison.

A: I'm going to do X, Y, and Z.

B: If you just do X, we'll meet the requirements.

A: I tried X Y and Z to fix my problem.

B: You can simply reinstall the IDE.

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

#210

Post by shri_krishna »

newswasboring wrote: post #189
shri_krishna wrote: post #143

Earlier quoted context omitted.

[flagged]

Classifying anything which is mental health related as "snowflakes" has lead us to many toxic traits in the current society. I would encourage you to take a harder look at what you are advocating here. To me it looks like to you taking anyone else's feelings into consideration is wasteful. I am sorry, I would rather work with snowflakes than bricks.

[flagged]
Post reply on HN