25 ms·

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 offe

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?

jstummbillig 3y ago
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.
vrnvu 3y ago
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.
- rco8786 3y ago
  > 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.
  - thunky 3y ago
    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?
    - ianbutler 3y ago
      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.
      - thunky 3y ago
        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.
        ianbutler 3y ago
        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.
WesolyKubeczek 3y ago
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.
newswasboring 3y ago
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.
- deleted 3y ago
  [deleted]
Muromec 3y ago
>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.
- imgabe 3y ago
  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.
  - spondylosaurus 3y ago
    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.
smcl 3y ago
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"
- warent 3y ago
  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?
- codeflo 3y ago
  > 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.
bjornasm 3y ago
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.
throwawaaarrgh 3y ago
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.
- peoplefromibiza 3y ago
  > 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.
  - throwawaaarrgh 3y ago
    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.
matsemann 3y ago
> Why is this so personal? It's simple to understand, really. How come you don't get this trivial thing?
zemo 3y ago
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.
- Frost1x 3y ago
  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.
nickjj 3y ago
> 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.
shri_krishna 3y ago
[flagged]
- newswasboring 3y ago
  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.
  - shri_krishna 3y ago
    [flagged]
    - Kye 3y ago
      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.
      - shri_krishna 3y ago
        No offense taken. Appreciate your input.
- jodrellblank 3y ago
  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?
wellpast 3y ago
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.
adolph 3y ago
> 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-girls https://jonathanhaidt.substack.com/p/mental-health-liberal-g...
qwery 3y ago
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 ...".
abootstrapper 3y ago
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.
pjmlp 3y ago
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.
bityard 3y ago
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.
- tetha 3y ago
  > 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.
jonahx 3y ago
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.
- ulizzle 3y ago
  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.
  - spondylosaurus 3y ago
    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.
    - ulizzle 3y ago
      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.
fdschoeneman 3y ago
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.
gyranthology 3y ago
> 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.
Kye 3y ago
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.
crazygringo 3y ago
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.
- jonahx 3y ago
  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.
- aschearer 3y ago
  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.
civilized 3y ago
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.
raydev 3y ago
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.
staunton 3y ago
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.
samtho 3y ago
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.
yieldcrv 3y ago
> 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
a_techwriter_00 3y ago
The psychology involved in the response you're wondering about is really quite simple to understand.
kristopolous 3y ago
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.
_gabe_ 3y ago
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.
lamontcg 3y ago
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.
WilTimSon 3y ago
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.
paulddraper 3y ago
Words have meaning. And 92% of the time, "just" or "simply" have no useful meaning.
lallysingh 3y ago
"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.
- ozim 3y ago
  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.
johnchristopher 3y ago
> 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 ?
tomcam 3y ago
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.
novok 3y ago
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.
stjohnswarts 3y ago
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?
GuB-42 3y ago
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.
dorkwood 3y ago
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.

jstummbillig 3y ago

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.

vrnvu 3y ago

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.

rco8786 3y ago
> 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.
- thunky 3y ago
  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?
  - ianbutler 3y ago
    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.
    - thunky 3y ago
      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.
      - ianbutler 3y ago
        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.

WesolyKubeczek 3y ago

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.

newswasboring 3y ago

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.

deleted 3y ago
[deleted]

Muromec 3y ago

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

imgabe 3y ago
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.
- spondylosaurus 3y ago
  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.

smcl 3y ago

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"

warent 3y ago
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?
codeflo 3y ago
> 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.

bjornasm 3y ago

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.

throwawaaarrgh 3y ago

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.

peoplefromibiza 3y ago
> 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.
- throwawaaarrgh 3y ago
  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.

matsemann 3y ago

> Why is this so personal? It's simple to understand, really. How come you don't get this trivial thing?

zemo 3y ago

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.

Frost1x 3y ago
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.

nickjj 3y ago

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

shri_krishna 3y ago

[flagged]

newswasboring 3y ago
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.
- shri_krishna 3y ago
  [flagged]
  - Kye 3y ago
    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.
    - shri_krishna 3y ago
      No offense taken. Appreciate your input.
jodrellblank 3y ago
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?

wellpast 3y ago

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.

adolph 3y ago

> 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-girls https://jonathanhaidt.substack.com/p/mental-health-liberal-g...

qwery 3y ago

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

abootstrapper 3y ago

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.

pjmlp 3y ago

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.

bityard 3y ago

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.

tetha 3y ago
> 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.

jonahx 3y ago

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.

ulizzle 3y ago
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.
- spondylosaurus 3y ago
  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.
  - ulizzle 3y ago
    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.

fdschoeneman 3y ago

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.

gyranthology 3y ago

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

Kye 3y ago

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.

crazygringo 3y ago

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.

jonahx 3y ago
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.
aschearer 3y ago
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.

civilized 3y ago

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.

raydev 3y ago

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.

staunton 3y ago

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.

samtho 3y ago

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.

yieldcrv 3y ago

> 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

a_techwriter_00 3y ago

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

kristopolous 3y ago

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.

_gabe_ 3y ago

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.

lamontcg 3y ago

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.

WilTimSon 3y ago

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.

paulddraper 3y ago

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

lallysingh 3y ago

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

ozim 3y ago
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.

johnchristopher 3y ago

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

tomcam 3y ago

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.

novok 3y ago

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.

stjohnswarts 3y ago

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?

GuB-42 3y ago

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.

dorkwood 3y ago

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.