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

191–200 of 299 posts

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

#191

Post by mistercow »

I disagree with this pretty vehemently. There is value in a doc telling you “this sounds like a complicated concept, but it’s actually not”. As a reader, it can tell you that you don’t need to dig for deeper meaning or start searching for and understanding all the related concepts.

This particularly comes up when a concept has an unfamiliar name because of how it fits in with things conceptually, but at its core it’s just a very familiar entity with some other familiar entity tacked on, or something like that.

For an example off the top of my head: “A tagged image is simply a JSON object with an ‘image’ data URI property, and a ‘metadata’ object property”. The word “simply” is pulling weight here. It’s telling the reader that there is nothing else to the concept, that they already understand everything there is to know, and they can move on.

This can be misused, of course, and I think the post’s example is a valid one. But it’s a lot more useful to say when you should use something in your writing than it is to say “you probably shouldn’t.”

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

#192

Post by ulizzle »

You shouldn't use "simply" because it's an adverb and an overused one, but this mumbo-jumbo about feelings is giving me the creeps.

The example given reads better because it cuts out the adverbs. I'm assuming Grammarly or something similar helped to lint it.

Such cringe.

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

#194

Post by bityard »

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

The main problems with the "just simply" writing are twofold:

1. The "just simply" words are completely unnecessary filler. Good writing is stripped of superfluous filler words. Writing with lots of filler words is harder to read because scanning, parsing, and then discarding them is additional cognitive overhead. This technology shit is hard enough as it is, save the flowery prose for your poetry.

2. As others have mentioned, the tone of the "just simply" writing comes off as condescending because it implies the author is considerably more knowledgeable than the reader, that the reader doesn't know anything about the topic at hand, and that the reader will somehow reach enlightenment once they are on the same level as the author.

It's not that I am personally offended by "just simply," it's just bad writing, and I won't read that kind of stuff unless I really have to.

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

#195

Post by jonahx »

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…

It's unfortunate that this is the top comment, because the "after" samples are clear improvements.

This is good old-fashioned writing advice, no different from Strunk and White's "Omit needless words" -- just tailored to developer documentation where a handful of specific needless words flourish.

The main reason to remove these words is that they are fluffy, superfluous marketing speak.

Do some people also find them condescending? Maybe -- I don't, but this is a side point.

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

#196

Post by desro »

I don't share the author's POV describing this sort of thing as "infuriating" or anything else that dramatic, but the before-and-after documentation example was definitely more readable and clear (I've never worked with rails [ruby?]).

So I support the overall premise here. It's nice to read documentation that is at least verbose enough to give you additional keywords to search with if you need more help, and I do feel a little bit more respected as a user when it feels like someone took time and care to write the docs with juniors in mind.

I think that a lot of the tutorials available on Digital Ocean are actually good examples of this; though they're not "docs" per se.

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

#197

Post by ulizzle »

jonahx wrote: post #195
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…

It's unfortunate that this is the top comment, because the "after" samples are clear improvements. This is good old-fashioned writing advice, no different from Strunk and White's "Omit needless words" -- just tailored to developer documentation where a handful of specific needless words flourish. The main reason to remove these words is that they are fluffy, superfluous marketing speak. Do some people also find them…

It's an improvement because it cut out all the adverbs. The tone of the essay is an unmistakable virtue signal.

It tries to correlate the virtue signal with quality improvement, which is either cringe or disingenuous.

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

#198

Post by fdschoeneman »

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…

I've never heard of anyone quitting because they objected to being told something which they find complicated is "simple," so this seems like a straw man.

I think a lot of people think about how best to teach complicated ideas. Maybe like me, they really aren't that smart, or even just feel like they aren't that smart, and when they read from an expert or an instructor or a professor that a thing is simple, that voice inside their head that is constantly telling them they're dumb or worthless gets louder, and they wonder if that vouce is right, and that the idea they are trying to understand is simple for people who aren't impostors and they should probably give up and shoot themselves.

Your professor used the word "trivially" in a stupid way. Similarly, technical writers and instructors use "simple" in a stupid way. Objecting to stupid language from teachers and technical writers that makes them less effective at their jobs doesn't make me a baby any more than celebrating it makes you an adult.

I don't think people who use words like this intend for their audience to feel stupid. But I don't see how they are helpful.

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

#199

Post by gyranthology »

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…

> people shouldn't be such babies.

Every time I've heard this sentiment in the corporate setting, it sets the ball rolling to create a culture that's hyper masculine and aggressive where people asking for help are seen as weak, unable, and shouldn't be "there". Okay, maybe not fully explicitly, but it influences discussions, how people communicate, and how reviews are laid out over time.

I'd argue that people claiming "people shouldn't be such babies" as the ones needing to be quarantined and separated out from making decisions that impact larger groups of people. It's clear that they can't put themselves in the shoes of others and know how to pull the best out of people.

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

#200

Post by Kye »

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…

This sure is a highly offended response from someone complaining about people being babies. If they're simply words, why does it matter if people criticize them? You could just move on. This seems like a personal and sensitive subject to you.

>> "What happened to the expectation of people being adults?"

Adults discuss things like adults: with empathy, fair reading, and hopefully a little kindness. They don't call other adults babies for raising issues.

Post reply on HN