Hacker News Reader

Comment by codeflo | Hacker News Reader

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

View on HN

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.

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

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.

Another way to put this advice on how to write with precision is: carefully consider any use of an adverb in formal writing (pun intended). Most adverbs in formal writing can be replaced by using a better adjective or verb. For some reason, adverbs like "simply" and "quickly" make people feel bad when the process isn't simple or quick, but using words like "straightforward" does not.

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.

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

But they are writing for an audience that is not as knowledgeable, so “simply” isn’t accurate for the audience, only the writer.

Yes, the author of that library knows more about that library. That doesn't mean they are generally more knowledgeable than me, and in fact they may be quite ignorant about the specific problem that lead me to investigate and learn the library in the first place.

Technical writer checking in to cosign everything you've said here. Most style guides advise against this kind of language for the exact reasons you outline—it adds nothing to documentation and it's pithy marketing-speak.

Don't hype up how easy it is to install your product... just tell us how to install the damn thing! :P

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

Also, completely on point, although in my experience product managers are far worse offenders than engineers.

There's room for debate over some of the advice in Elements of Style, but "omit needless words" is a great one that every expository writer should take to heart. The advice to use common words in favor of "fancy vocabulary" is also good.

When you hire new people and they encounter this over and over again, onboarding drags on so, so much longer than it should, because people taking your position never think "we should reduce how complex this is", they think "they should stop being babies", and things just get progressively more obtuse and annoying and require more and more tribal knowledge instead of making sense.

It's not the word "simply", it's that if you think every thing that's easy for you is therefore easy, you're communicating that you don't think that understanding other people's experience matters.

The issue often more has to do with how others interpret simply. Someone working in some code base who has some arcane undocumented process and structure to get something functioning or has developed some abstraction over the years may, relative to themselves, think the specific task is "simple." They've lost context of the actual full process and set of abstractions for someone else because they've been so immersed in that space.

For most people working with someone like this directly, that's fine and dandy. I know the process isn't actually simply, I know there's a lack of information, and I know there's a significant hidden time component for someone else to step into that space either if it's me handwaving away complexity or if I'm being handed something that handwaves it away.

The real issue here is that opinions of those people don't matter in terms of the interpretation of complexity. It's the bystanders who don't care about any of the technical pieces. They just want Alice to take over where Bob left off and move on to get the functionality they're paying to get. Bob can gaslight Alice that it simple all day and Alice isn't naive, she knows better.

But business manager Carson is unaware of this and also doesn't care, at all, and when Bob says it's simple while Alice is struggling and Carson starts pressuring Alice like she's an idiot or incapable and Bob steps in and does said task quickly, it looks bad on Alice. If Carson is a good technical leader or manager, they know what's actually going on and Alice may not be incompetent, Bob just has poor documentation or has lost touch with reality. Carson is rarely a good technical manager and has others pressuring them, so you're left with how "simple" something is looking bad on Alice in almost all cases.

This is why developers hate when you handwave away complexity. Do future people a favor and don't pretend something is simple if it's truly not. Think about the entire process you went through to get to the point you are and the set of prerequisite knowledge and patterns you have to do what you're doing. Of course, if you want job security, make Alice and everyone else look bad and keep making everything you do overly complex, vague, and with large gaps of explanation.

Well put, and this harks back to the classic Rich Hickey talk "Simple Made Easy". For Bob the process is easy because he's internalized all the complexity. It's not actually simple. But it's subject to the conflation of "simple" and "easy" that Hickey warned about.

Another way to it has been put is "beginner's mind" or the "curse of knowledge". Once Bob has mastered the many intricate steps it is hard for him to see them clearly and remember the difficulty he himself had. A truly simple process on the other hand would be (relatively) easy for everyone, not just the expert. And of course as you point out it can be difficult for a removed observer to tell the difference.

This is literally a blog post about not using words like simply, not about reducing complexity or how to share knowledge across progress stages.

Some of us in this thread seem to be taking this blog post to project our past experiences onto, but this post is quite literally just about not using words like simply.

Also nobody will ever take the word literally from me, I will ensure all docs I come across use it bountifully!

connotation exists, you know

It does, generally. However you've failed to demonstrate such enough to remain on topic from what the article is actually saying and to what you posted. So much so I would assume you haven't read the article before you posted.

I read the article, you're refusing to see the forest through the trees.

If you don't understand something then you're in the perfect position to improve the docs. Others who are already familiar with the project may not think they need to document it, because they see it as simple.

This is an important lesson. Anytime you're onboarding a new user/employee, your documentation will benefit by getting that person's feedback. What's incorrect? Where there any steps that weren't clear? Or missing steps? Is there information that's outdated?

I've even gone as far as forcing the developers to answer questions by incorporating new information into the documentation. If you start having out-of-band communication (email, chats, in-person conversations) between the newbie and the team, there's a strong chance that extra information will never find its way back into the documentation.

This is such a bizarre take. The post is about removing some unnecessary wording from technical documentation that doesn't add anything, and as an aside can sometimes imply complex tasks are simpler than they are to the detriment of the app/library/service it's documenting. I have no idea why you'd think this implies some personal failing or that it is advice for "babies"

Agree wholeheartedly.

Most people are comfortable making incremental improvements in all our tools and comforts in life, so why should communication (the greatest tool of all!) be any different?

We can make a knife with a better handle or keyboard with better shape, and it's called "ergonomic." Nobody claims someone being a baby for wanting that.

Meanwhile, a small suggestion to enhance how we handle communication is met with such severity and perceptual distortions, as though the ones making the suggestions are having some breathless emotional psychosis. Why?

> The post is about removing some unnecessary wording from technical documentation that doesn't add anything, and as an aside can sometimes imply complex tasks are simpler than they are to the detriment of the app/library/service it's documenting.

I'm not sure that's a fair summary of the article. I just reread it: at no point does it suggest removing superfluous words in general, it's specifically about "words such as easy, painless, straightforward, trivial, simple and just", because those in particular are "jolting", "upsetting and annoying" and "infuriating". What you frame as an "aside" is in fact the first and last paragraph of the article.

> I have no idea why you'd think this implies some personal failing or that it is advice for "babies"

You're missing a level of indirection here, the readers of the documentation are the “babies”, not the writers who take this article's advice. This is advice for people who write for people who act offended when reading the word "simply" in technical documentation, and I'm questioning the dynamics of that.

It's obviously fair to criticize the word choice on my part, there were less incisive ways to phrase that. But then, it's the article that claims that the usage of the word "just" in the sentence (the article's example) "[then] we will just edit the users_controller.rb" is "condescending", and I think that's "simply" (sic) insane.

john lennon once said "never use 'just' in a lyric - it's lazy" (i paraphrase) and i think he might have had simmilar opinions on such things as "trivial". sadly, we will never know.

* He used 'trivialities' in a song (When I Get Home)

* She was "just" seventeen (arguably that was Paul's line, but John didn't override it, and kept his name on it)

* "(Just like) Starting Over" has 'just' in the title and lyrics.

* "Just" gimme some truth.

* "I'm just a jealous guy"

Rules are meant to be broken, perhaps? Or maybe he would just cop to being lazy?

> Rules are meant to be broken, perhaps? Or maybe he would just cop to being lazy?

both?

the quote i paraphrased was from hunter davies' authorised biog of the beatles

but i still think it is a good rule

i don't completely disagree. I wonder how much of that was a flippant remark, how much his own views changed in the intervening years.

> The post is about

Please reread the comment you are replying to. He’s talking about the hacker news comments.

The very first sentence of their comment is an appeal to the article. They're addressing the article and using HN comments as evidence to reinforce their perception of it.

"Stop saying how simple things are in our docs"

"Or maybe -- controversial opinion here -- people shouldn't be such babies"

Yes, it’s possible to alter the meaning of something by quoting a sentence out of context.

If you continue reading to the next sentence, it becomes explicitly clear that he is addressing the comments here.

> that doesn't add anything

tbh I enjoy when documentation gives me an idea of the effort required to go trough it. is it just copy pasting commands? does it require any configuration for achieving different goal? am I supposed to handle prerequisites on my own? Is there any passage that require my attention or everything will break down the line?

now, "simple" may not be the correct wording for it, but still I wouldn't say that there's no value in indicating the effort beforehand.

>What I wonder is: Why is this so personal?

Looking at example given at this page, before the edit -- it looks like whoever wrote the library is being proud of this little trick they just invented. Look, look, mailer is just another kind of a view! Appreciate how neat it is that we don't invent another high-level concept but reuse existing stuff in a slightly different way. This is personal. Example on the right skips this part and focuses on how to use things.

Being proud of "this little trick we invented" is good ofc, but maybe it's place is in a conference talk or into video of something. Maybe whoever is reading the doc is not your mom and doesn't care right now.

It's a bit of a cultural shift from a community of cool people showing cool stuff to each other to more "it's just a job" kind of attitude. If you aren't there to appreciate clever tricks, it's just noise.

Nah we don’t need to strip out every ounce of personality from something someone was kind enough to write and share for free. Anyone whose delicate sensibilities are so offended can just simply write whatever free library they’re using themselves.

This advice extends far beyond free libraries (and the linked article makes no indication that it's specific to that context). I've encounter all kinds of B2B SaaS docs full of worthless bloat, and I've written docs in the face of pressure from product teams who want to turn documentation into a Look How Cool We Are showcase.

And docs can be clear and straightforward without reading like stereo instructions—you can convey plenty of personality through tone and voice.

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

I dont know about taking it personally, but it is very annoying to me. It is also misleading, because most of the times it is not simple by most definitions. I like my documentation to be concise and give me information, not make effort estimates for me :D. I know it's a silly point, but it is very grating to read. I would file this under bad writing practice.

I could tell you you're missing the obvious answer, but that doesn't help you understand the thing you're missing. I could tell you the YouTube tutorial that starts from scratch has a very simple and obvious reason why it starts there, that a lot of other people get that you don't. But that doesn't help you either. And I could tell you that infantilizing someone who's having a hard time understanding something is the opposite of adult, but that doesn't tell you why.

> YouTube tutorial that starts from scratch has a very simple and obvious reason why it starts there

what's the reason in your opinion?

Because in my opinion a programming tutorial that starts from installibg the IDE is like a recipe tutorial that starts from how to use a gas stove.

it should be two different tutorials, at least

It is clearly important to understand how an IDE works, but that's the kind of knowledge that should be implied when you watch a programming tutorial.

Otherwise you need to learn two things at the same time.

Besides, IDE are usually complex enough that the two sets of skill don't overlap, so if the tutorial focuses on the programming and skims over installing the IDE, it is assuming that you can "simply" or "trivially" install an IDE such as Jetbrains Idea and be immediately ready to use it proficiently enough to learn something else with it, instead of fighting it to get things done. Which is usually the case, when I teach programming at work I focus on the programming using slides or some basic live coding using a very basic editor (vanilla sublime for example), because if I start using IDE features, people start making a lot of questions on how to do the things that I am doing that I don't even realize that I am doing them without even thinking about them, to the point that it becomes an IDE focused training. Showing that you can't take for granted that installing an IDE is a good starting point. It raises more issues than it solves.

I'm quite sure it would have been much harder for me to study Italian literature while I was learning how to read.

One of the things I do for a living is write documentation. I have the privilege of supporting a lot of different types of users. And within each type of user, there is variability.

For every document I write, there are always a couple people for whom my document fails. It's not because they're stupid, or because I am. It's because communication is hard, and different perspectives change how information is processed. In addition, in many cases, there's simply a different use case that my document didn't account for because I didn't think of it or run into it.

So much of the time, I need to amend documents after the fact. I may need to clarify a statement, or provide alternate instructions. Often it's a detail that I thought should be universal but wasn't. And often users will simply have done something different beforehand, or out of order, or in some way not in accordance with the intended instructions.

Therefore, if I want a user to be successful with my document, it has to be complete, and thorough, and be tested by different people. It needs to not make assumptions, and it needs to be clear and concise so it can be followed in one go.

If you start getting fancy and make 50 different documents for different steps, because "logically" that makes more sense, what you will find is the user will run into a problem that the two separate documents didn't consider when taken together. Then the user will stop and try to find someone to fix their issue.

If you don't want to be tied up in support calls your whole life, one complete document is the best solution. And if you're a user who just wants to try out some sample tutorial, one complete document is the most likely to work for you without taking up more of your time.

The YouTube video that shows you installing the IDE is superior to one that doesn't. And for pete's sake you can always skip through it.

> The YouTube video that shows you installing the IDE is superior to one that doesn't

I disagree.

That's assuming that your time is infinite, the user time is infinite and you are writing a tutorial about everything.

It's usually not the case, the best documentation I have found is the kind that focus on what it is about and only that.

It doesn't imply that an introduction is not necessary, it implies that you will talk about what's in the title of the document and only that. You have to assume a certain level of knowledge, you gotta stop somewhere and say "they must know this already or this is not for them" otherwise any documentation should include a chapter on how to download the software you are about to install and how to, why not?, connect to a WI-FI network. "A tutorial that talks about it is superior to one that doesn't" isn't it?

YouTube videos do that because the algorithm rewards longer videos, tech writers to that because it makes the final document larger and larger is always better than smaller, if you are paid for the words you write.

The laziest documentation I have found is the one that starts from the origin of the universe and it only resolves in the last 5 paragraphs, "drawing an howl" style, even though it should only be about drawing the damn howl.

One infamous example is Coursera coursers, each one of them presents the same exact intros, like if it's Java or Scala, they start on how to install Intellij Idea and the first assignment is compile a project and send it to show you understood how it is done. Except the course is called something like "Writing highly concurrent distributed systems in Scala", it is marked as an advanced specialization and it makes no sense to take it if you don't know how to install an IDE. But even assuming it happens, it could be easily solved by an FAQ. And BTW you have to complete the first assignment even if this is the nth course you're taking on the subject, you already installed Intellij, already compiled a project and already completed the assignment n minus 1 other times.

Do you also believe that teaching people how to drive a car should start from how to buy one?

> what you will find is the user will run into a problem that the two separate documents didn't consider when taken together.

the opposite is usually true in my experience.

You will find that most of the times the people that are actually interested in the documentation, will be much better off with a more succinct version of the same document.

> If you start getting fancy and make 50 different documents for different steps, because "logically" that makes more sense,

Nobody said 50 different documents. Just separated the "tools setup" from the rest of the documentation or put it in an appendices at the end.

The "setup" section in most Github repos are very welcome, if they are in the in the form

  * do this
  * do that
  * run `docker run ... -p ...`

if they were of the form "Docker is an open source platform that enables developers to build, deploy, run, update and manage containers ..." and then went on with the instructions on how to install it on every single platform, I would close the browser's tab and look somewhere else. Just refer to another document that explains it all in details for those who might need it and be done with it.

I dont think its personal, at least it isn't for me. Its because it is wrong. If it is documentation intended for people new to this its better to explain everything, and avoid making assumptions about what is simple or not. Its so much better to just have documentation of everything or to refer to it.

I don’t think “offended” is a fair assessment of how people react to these types of filler words. I think we tend to forget, especially after reading and writing computer languages, that our human languages are meant to be read and understood by other humans and our words can have a powerful effect on others. As the blog post suggests, this does seem to come out of a place of excitement to share knowledge, but it can come across as off-putting or disingenuous if, for example, something described as “simple” is not. Regardless of how fragile others are and conversely how tough you think you are, we are all affected by the way things are worded, with each of us carrying our own baggage and differing understanding of specific connotations. This is, however, not about adding bumpers to our language so that nobody feels hurt, it’s about communicating concepts and instructions in universally clear language that is not muddied with fluff or superlatives. In other words, it’s a UX problem.

For the record, I don’t disagree that people seem to be offended easily. Often the least charitable meaning is assumed and people escalate/react accordingly. Many individuals have become trained to fixate so heavily on micro aggressions that the context and tone of messages is lost and these people become difficult to interact with and a cycle of misery ensues where they find themselves surrounded by people who only walk on eggshells when communicating.

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.

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.

Completely disagree that this is a form of virtue signaling; everything the article outlines is reflected in the major documentation style guides (e.g., MMoS or the Google developer documentation style guide).

- Don't make unsubstantiated claims about your product.

- Don't discuss upcoming features or refer to existing features as "new" outside of announcements/release notes.

- Don't make promises about uptime or other things that belong in an SLA—this can have nasty legal implications down the line.

- Don't waste time with marketing-speak; your reader is either already using your product or is on the verge of using your product (and consulting the quality of your docs before they decide to move forward).

- Don't use ambiguous language or cultural idioms that may confuse ESL readers.

- Don't preface instructions with how easy it is to do something; every reader has a different level of experience and background knowledge. Also, if you say that your product is easy to use and then it actually isn't, it makes you look like an idiot. Or disingenuous. Or both.

If you completely disagree, keep in mind “completely” is also an adverb.

Some frameworks sell simplicity (setup, maintenance) as a feature, so that adverb would be fitting.

But this is just infantilizing and a lot of people (maybe a universal trait) are annoyed by that.

What? Adverbs are fine; there's no industry-wide dictum against adverbs.

I think you might be mad at something different than the principles I'm outlining here. These are accepted standards of technical documentation.

This is basic English grammar, something you should have learned in grade school.

Your grade school taught you that adverbs are a form of virtue signaling?

No one will fall apart and burst into tears because of an adverb they read in the mountain of documentation we have to read to get the job done.

Navel-gazing of the highest order.

You lost me there again, my friend. Technical writing stylebooks draw no correlation between adverbs and nervous breakdowns. You seem to be tilting at an entirely different windmill than the one I'm tending to.

That's fine, but put your marketing copy in your marketing, not in your docs.

If good documentation is a virtue signal, then yeah, I guess?

This post is a shallow public display of faux moral superiority from the language police.

I miss Linus Torvald's legendary snark and the epic flame wars of yesteryears.

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.

> Why is this so personal?

It's simple to understand, really. How come you don't get this trivial thing?

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

I think this really proves that writing good documentation is a skill you can hone.

In my opinion, if you're writing a package, gem, etc. for a web framework:

Having extremely concise documentation where you assume the person using your tool is already an expert, so you skip everything except for the precise details related to your tool can be frustrating for anyone looking to use your package unless they happen to be at a skill level where they could have written the package themselves. If folks can't figure out how to use your tool, they'll use something else.

Having extremely verbose documentation to the point where you rewind things back to installing an IDE or explaining what a for loop is for an extension related to pagination is equally as frustrating for most folks because they already have the basics down and want to figure out how to use your package.

I'm a firm believer that good documentation for such a tool or package would include the "why" with a few practical examples along with a guide-like approach of explaining how to get it to work where you use title headings and bullets to make it skimmable as a reference at the same time. You can still make it concise while covering all of that ground. I see nothing wrong with having both text and video.

This way you satisfy a wide range of skill levels without frustrating or alienating anyone. This approach isn't coming at it from an angle to "protect" anyone either. It's optimizing for general success where success is defined as anyone other than yourself can use the package with minimal'ish friction.

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.

> Nowadays, people seem to be overly sensitive about their code and the way we communicate, among other things.

If there's one thing I've learned in life, anytime you see "Nowadays" or "these days" or something similar, you can be guaranteed that whatever statement follows it is a universal truism about the human condition that recency has no bearing on.

People are sensitive about their work. And sensitive to how we communicate together. Always have been. Always will be.

So you're saying people as a whole don't change behavior over time?

It's not possible that the average modern software developer is just a bit more sensitive about their work than a welder was in 1950?

I've known people who talk about their welding skill and would be unhappy if you pointed out their joint looked like crap.

People, in general, are sensitive about anything important to them.

I was trying to compare equivalent professions across time periods, not to suggest that welders are any different than developers.

I would not be surprised if modern day welders get offended by their equipment manual as well.

I A. Don't see significant similarity between welding and programming B. Think that you would be wrong about people being annoyed about things that make their work harder across any time period.

The difference is how people expressed those emotions or not, not whether they had them.

> The difference is how people expressed those emotions or not

That's a change in behavior.

> It's not possible that the average modern software developer is just a bit more sensitive about their work than a welder was in 1950?

I was responding to this. My answer is no. Whether they express it or not, I imagine the sensitivity hasn't increased. You can feel something (being sensitive) without choosing to express it.

Emotional control is something well-adjusted people do every day, regardless of what they are feeling. It is simply more acceptable to express these emotions now.

If I had to guess people in the 50s just died inside and then drank themselves to death instead. Or took it out on their families.

> So you're saying people as a whole don't change behavior over time?

At a fundamental emotional level, yea that's pretty much what I am saying.

> It's not possible that the average modern software developer is just a bit more sensitive about their work than a welder was in 1950?

Maybe. It's possible that the selection of 1950s welders consisted of a fundamentally different slice of the overall social profile than coders of the 2020s. But overall sensitivity comes with pride. If 1950s welders had pride in their work I am certain they had sensitivity about it also.

But the statement was "Nowadays people seem to be oversensitive about their code". So you have to compare people who write code now vs people who wrote code in the past. Not two different professions.

Because when you use phrases like “just simply” [do something actually hard], your stakeholders read that and say things like, “why did this take a whole sprint to implement? You said you just had to [do something hard].” There’s no reason to downplay the difficulty of your and your team’s work.

Further, we’re adults, as you say, so let’s be adults and take the time to consider our readers position and how our writing might be interpreted. You’re doing no one any favors by refusing to be empathetic.

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.

"Simple" reads "simple for me" (the author). That can be really frustrating at times.

But the real sin here is wasting words on useless bullshit. Just get to the damned point. "Just simply" is 100% waste. I can replace "Just simply verb" with "verb" and the sentence is already better, without putting a bunch of emotional loading into the context of the discussion.

Part of article about "sharing excitement" I would rewrite:

Stop writing "it is easy - just do x" because it is plain marketing bullshit that people are compelled to add to documentation or website describing library/tool only for a reason that - they think they should do it.

> What happened to the expectation of people being adults?

The below quotes from Haidt summarize the concept that culture at large is promoting an inverse of CBT. As a result the knowledge increasing method of criticism has been hijacked by folx channeling their inner Foucault.

CBT (Cognitive Behavioral Therapy). In CBT you learn to recognize when your ruminations and automatic thinking patterns exemplify one or more of about a dozen “cognitive distortions,” such as catastrophizing, black-and-white thinking, fortune telling, or emotional reasoning.

. . .

Greg hypothesized that if colleges supported the use of these cognitive distortions, rather than teaching students skills of critical thinking (which is basically what CBT is), then this could cause students to become depressed. Greg feared that colleges were performing reverse CBT.

https://jonathanhaidt.substack.com/p/mental-health-liberal-g...

When I read the OP's example rewrite ("Calling the Mailer") I find his rewrite to be far less patronizing than the original.

Ironically, the original one -- with all of the supposedly "offensive" copy -- reads like it was meant for babies.

I'm not offended by that, it's just annoying and distracting. His rewrite is remarkably better.

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.

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

Nah, it's fluff. Write good technical documentation, not your wishy-washy feelings about how easy or hard it is.

edit: write like you'd write an RFC.

> Or maybe -- controversial opinion here -- people shouldn't be such babies.

Seriously, why is the introduction of the top comment a thinly veiled insult disguised as a weak rhetorical device ?

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.

I completely empathize with this sentiment and understand where you're coming from. However, I've been writing tutorials and documentation for awhile now, and while editing my videos I realized that I would often say "see, simple" after explaining a topic (which is equivalent to just simply in my opinion). I realized that 99% of the time I said that, it was filler and unnecessary, almost like a nervous tick.

Aside from that, of course it's simple for me! I'm the one writing the documentation or creating the tutorial. I've tried to simplify the material into digestible steps. However, this also means I know the subject at hand inside and out. My target audience doesn't necessarily know it as well as me.

So, instead of saying, "see simple" in my tutorials, I began asking myself, "is this concept truly simple for my target audience?" If it isn't simple, then that points out an area I need to clarify and simplify further. I only consider the video/documentation done when I can truly say to myself that the technical content is concise and simple enough for my target audience. This leads to better technical writing (no unnecessary filler), and it leads to a hopefully thoroughly thought out description of the material at hand.

So I don't believe people are being babies or shamed into quitting their careers over a misplaced "simply". Rather, I think they're subconsciously understanding that the writer of the documentation wasn't ruthlessly cutting down the material. I think "just simply" often points to lazy writing, and people pick up on that. Good documentation is ruthlessly concise, truly simple (as in its reduced to the smallest piece of information possible), and it conveys the necessary information quickly.

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.

This is a useful framing, and personally I learn hard toward the "speaker is responsible" strategy.

With that said, I think a continuum is an even more accurate framing. If you are confusing your audience, it is probably your fault. But not necessarily. Some people won't make an effort, will be distracted, or will engage in bad faith. I see it as a negotiation in which you should be strongly biased toward the audience being right.

Nailed it.

You got me thinking with your "two ideologies"... I think it's more accurate to say, there are different modes of communication with different goals. At a minimum, there's sharing information, entertaining, social signalling, fighting/arguing. The relationship between speaker and listener varies in each case. Vocabulary, turn of phrase, tone all contribute. It's wise to figure out which case you're in and adjust accordingly.

Newbies get into loops by thinking the solution is simple when it's complex from their perspective and can go off rabit paths and waste time. Kind of like the opposite of overthinking a solution when the solution is simple. It's a writing linter.

I suppose it depends whether you’re writing documentation that you want people to read or not.

I often have to write documentation for non-technical people, and if they don’t understand it or they find it too discouraging to follow, it makes my job harder.

I can yell and shout all day about how they should just get a thicker skin and study my words more thoroughly, but it won’t change human nature. Eventually you need to stop wishing humanity was different, and accept humanity as it is.

It's not that the inclusion of this one word is offensive and so the entire product is ruined. It's a matter of accessibility. The more of it (accessibility) your thing has, the more accessible the thing is.

Why add something to your product that some users find makes their time with your product worse? If there is little to no reason[0] to include a feature and removing it could help some users, then not including it or removing it is a no-brainer.

> One month in,

If it took you a month, it sounds like it wasn't trivial. As presented, it sounds like your prof saying that was pointless at least.

[0] In this case, it's hard to see any benefit at all from adding the "simply ...".

The thing is, even if the "simple" thing is indeed simple, why write it down? It is most likely a useless word and your writing will be clearer without it. There is a good example in the article.

This is something editors will tell you, be it for fiction or for technical writing: make every word count, remove the fluff.

As for "trivial" in math proofs, knowing how codified math is, I guess there is a precise use case for it. But I don't usually see math proofs telling me that "2+2=4" is trivial, they just write "4", and that's what the article suggests.

Resilience and good communication don't share an axis. You can want and have both. To me, the examples in the article make a convincing case for what's stronger writing and that's good enough.

One of the rare times where I agree that someone being infuriated by these words is a bit ridiculous. It's not like they're offensive or emotionally manipulative, it's merely a matter of someone's style of writing or just a means of encouraging someone to do the task that might otherwise seem daunting by virtue of being one of a hundred tasks they have to do that day. It can be annoying but complaining about hyperbolic words and then saying they are "infuriating" is a tad ironic.

I like your perspective in general. The reason I don’t mind getting a little bit worked up about it is because most documentation is terrible and that can make people frustrated and feel bad when it doesn’t have to. Which plays into your point, but spreading this over thousands, or millions of users seems like a terribly unproductive strategy. If you correct the documentation, once you will make many people's experience better over the life of the documentation.

I am on the same page, for whatever reason everyone is fragile now, and we need to make all efforts to avoid breaking things into thousands of broken glass pieces.

This whole feel good censorship feels no different from the old days, when my previous generation had to measure every single word, not that PIDE/DGS were going to be made aware of it.

More controversial opinion is that there's too much ego-stroking fluff in general and everything is "perfect" and "elegant" and "awesome" and "simple", etc, etc, etc. Always reads like appeals to narcissism to me.

Is it really a big deal that people would like to just simply ID it as a grammar issue and basically is simply a useless phrase as it will be simple for some but not so much for others and let them judge how simple it is for themselves?

It signals the authors incompetency and is a red flag their code is a bug ridden hot mess caught up in ego stroking bullshit.

Simple, easy, lightweight - any project with that in the name is a sprawling trashpile.

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.

> isn't that a clear hint that I'm still missing a concept somewhere and need to look around for an explanation?

No, it means you are being gaslit by an autistic nerd, there was no committee going over those docs it’s just one person’s interpretation and attempt at interacting with the rest of society

I agree with your general idea and great! Now we can just copy and paste the docs into chatgpt for a real explanation and move on

The psychology involved in the response you're wondering about is really quite simple to understand.

Words have meaning.

And 92% of the time, "just" or "simply" have no useful meaning.

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.

Reply on news.ycombinator.com