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

211–220 of 299 posts

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

#211

Post by Kye »

shri_krishna wrote: post #210
newswasboring wrote: post #189

Earlier quoted context omitted.

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]

Apologies if this causes offense, but: you have a single, formidable paragraph with nine questions in it. This is a lot to put on a reader all at once. Consider breaking it up a bit. That many questions all at once can feel more like an interrogation, while good communication feels like a conversation.

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

#212

Post by yellowapple »

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…

> the tone of the "just simply" writing comes off as condescending because it implies the author is considerably more knowledgeable than the reader

If the author of some library was not considerably more knowledgeable than myself, then I probably wouldn't be poring over said library's documentation.

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

#213

Post by shri_krishna »

jodrellblank wrote: post #207
shri_krishna wrote: post #143

Earlier quoted context omitted.

[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 le…

> 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".

Bad analogy. It literally applies to the article itself.

The left: Mailers are really just another way to render a view

The right, having a meltdown over "just" and "simply": Remove "just" and "simply" else it will ruin my flow of thought and is "jolting" to read. It comes off as "condescending", is "upsetting" and "annoying"; removing "it doesn't put people off".

----------

> 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?

No where did I say anyone is inferior to me? I said some are snowflakes and get offended by the most random thing imaginable and there is no obligation to cater to everyone's whims and fancies. Who would have thought words like "just" or "simply" can offend anyone? But here we are discussing if words like "easy, painless, straightforward, trivial, simple and just" offend people or not.

Also, the "imaginary group of people" are the ones we never hear about. We only hear about the successful ones who toiled their way to become what they wanted to become without whining about everything along the way. My limited point is: if you really want to whine, there are much better things to whine about than language/tone of innocuous words in the documentation.

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

#214

Post by shri_krishna »

Kye wrote: post #211
shri_krishna wrote: post #210

Earlier quoted context omitted.

[flagged]

Apologies if this causes offense, but: you have a single, formidable paragraph with nine questions in it. This is a lot to put on a reader all at once. Consider breaking it up a bit. That many questions all at once can feel more like an interrogation, while good communication feels like a conversation.

No offense taken. Appreciate your input.

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

#215

Post by taeric »

Simplicity is asserted as much as it is true. Such that, you will be surprised how effective saying something is simple is at getting uptick in it. My goto evidence for this, for a while, has been Python. It is no "simpler" than pretty much any other option nowadays. What it has going for it is an audience that as bought in to how simple it is. And they evangelize it. With those terms. Heavily.

Is it somewhat obnoxious? I mean, yeah. I'm very sympathetic to the idea. At old job, we would harp on "weasel words" that were there and served no purpose. But, there is a catch, they absolutely work on audiences that are not primed against them. Can they be overdone? Absolutely, but there are solid reasons you will see them over and over.

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

#217

Post by oldsecondhand »

sametmax wrote: post #181
KMnO4 wrote: post #152

Earlier quoted context omitted.

GPT != Chat GPT, GPT-4, etc. It’s possibly to [“just simply”] train a GPT on whatever corpus you want.

You can train GPT 2 on whatever you want, it will give you the wrong answer for everything. The real magic arrived with GPT3, which is proprietary, so it's fair to assume your audience understands this and imply it.

GPT-3 is opensource. GPT-4 isn't.

https://github.com/openai/gpt-3

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

#218

Post by raydev »

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…

At best, "trivial", "just", "simply" are all noise words. They add no context.

At worst they are targeted at the wrong audience. The writer doesn't actually know how knowledgeable or experienced the reader is.

So if you're a writer or you're simply (heh) writing docs for a library you're working on, and you're decent at this task so you take a moment to reflect on how your audience might read your writing, why would you use the word at all?

> 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?

Instead of falling into the trap of "kids these days" short-sighted whining, perhaps consider that the barriers to creating and sharing content have never been lower. More content targeted at beginners seems like a natural conclusion to me, since it reaches the widest audience.

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

#219

Post by MrJohz »

grog454 wrote: post #209
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…

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.

I think "simply" as a synonym for "instead" is part of the problem here. "Instead" is probably the better option in most cases. For example, in the case you gave, "instead" is the clearer word choice because it clarifies that you are (only) presenting an alternative course of action, rather than offering a value judgement on that action. Similarly, "only" is generally better than "just", because again, it tends to be less loaded and more explicit.

This won't be applicable to all writing - writing for entertainment or to make an argument will look very different - but in technical writing, clarity is key, and words like "just" and "simply" are usually less obvious than their "only" and "instead" counterparts.

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

#220

Post by staunton »

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…

The opposite view of what you criticize is the Stockholm syndromey "documentation is for losers" where you should "just read C-headers for how to interface, or the actual library code to figure out what the library does". In this view, asking for help or admitting to not knowing or understanding something is a sign of weakness and incompetence. Thus, people who ask questions aren't worth a competent™ person's time.

My view: the purpose of documentation is to help people achieve their goals using your tools. Do everything that helps this purpose and don't do things that don't help it.

Does the occasional "simply" help the purpose? I would say it almost never does. Telling users whether a step is simple is meta-commentary that distracts from the actual steps and is only useful if it helps people make decisions ("choose way X to do Y because it's simple"). People who sprinkle "simply" into documentation seem to rarely think about whether it serves a real purpose.

50-minute step-by-step tutorials are very useful when your goal is just to do that thing. This conforms to my view that tutorials and documentation serve the purpose of allowing people to achieve goals.

You might feel instead that there should also be some pedagogical goal. People who read your documentation should become smarter, think outside the box, learn patience and perseverance that is required for their craft, etc.

I think the real debate here is about this fundamental distinction of what purpose documentation serves.

Post reply on HN