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.
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.
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?
People, in general, are sensitive about anything important to them.
I would not be surprised if modern day welders get offended by their equipment manual as well.
The difference is how people expressed those emotions or not, not whether they had them.
That's a change in behavior.
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.
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.
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.
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.
And docs can be clear and straightforward without reading like stereo instructions—you can convey plenty of personality through tone and voice.
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, it's advice for people who write for people who act offended when reading "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 obviously 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.
* "(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?
And paraphrasing: Imagine there's no absolutes. It's easy if you try.
both?
the quote i paraphrased was from hunter davies' authorised biog of the beatles
but i still think it is a good rule
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 or keyboard with a better handle, 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?
Please reread the comment you are replying to. He’s talking about the hacker news comments.
"Stop saying how simple things are in our docs"
"Or maybe -- controversial opinion here -- people shouldn't be such babies"
If you continue reading to the next sentence, it becomes explicitly clear that he is addressing the comments here.
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'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.
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 time.
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 ...`
It's simple to understand, really. How come you don't get this trivial thing?
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.
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.
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.
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!
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.
I think this really proves the point 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 once saw a video of how astronauts who visit the International Space Station had to learn Russian as everything in the Soyuz was labelled in Russian. Had to even read documentation written in Russian to be able to operate Soyuz optimally. None of these snowflakes would have survived such demanding jobs.
One positive thing about AI revolution and ChatGPT is that we can finally get documentation automated out of the equation and introduce neutral language. This shouldn't even be a problem going forward. A prompt for "Important: rewrite this documentation in as non-offensive way as possible while blacklisting words such as 'just', 'simply'" etc should do the trick.
So you are implying that the person who wrote this article is suffering from some "mental health issue". I never implied that anywhere in my comment. I called people who require you to adjust to their expectations of what normalcy is, to be snowflake behaviour (which is also the definition of a snowflake btw, if you look up the dictionary). I gave an example of how non-native English speakers already find it hard to write documentation in English in the first place. Now you want people like us to also take into consideration your "feelings" on what words trigger you and what don't before writing a technical documentation? Seriously? What would you do if I wrote the documentation in my native language instead as I am most comfortable in it? I am already going the extra mile in communicating with you in English. Now you want me to stretch that even more to consider your "feelings" too? How about you and I meet in the middle? I'll write documentation in Kannada (which happens to be my native language), and you put the extra effort to read the documentation in my language or get it translated yourself? Would you be comfortable doing that since you "rather work with snowflakes than bricks". Would that work? If not why not? And if you refuse to understand my "feelings" should I call you a "brick"? Everyone faces difficulties learning stuff in their own way. Some are not even proficient in English to even begin to understand the documentation, let alone discern if "simply" or "just" is triggering them or not. Yet most go through with the struggle without creating a fuss or blaming the author of the documentation (who also might be going through their own struggles).
All I am saying is we all have (as a dev community) much harder and pressing problems to solve. Crying over whether to use "simply" or "just" in documentation is not a battle we should be picking. That's my limited point.
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?
Bad analogy. It literally applies to the article itself.
The left: Mailers are really just another way to render a view
The right, having a meltdown over "just" and "simply": Remove "just" and "simply" else it will ruin my flow of thought and is "jolting" to read. It comes off as "condescending", is "upsetting" and "annoying"; removing "it doesn't put people off".
----------
> Why does this happen? Why are you so insecure that suggesting a way for documentation to be made clearer makes you conjour up a fantasy about an imaginary group of people who can't learn Russian so that proves they're inferior to you?
No where did I say anyone is inferior to me? I said some are snowflakes and get offended by the most random thing imaginable and there is no obligation to cater to everyone's whims and fancies. Who would have thought words like "just" or "simply" can offend anyone? But here we are discussing if words like "easy, painless, straightforward, trivial, simple and just" offend people or not.
Also, the "imaginary group of people" are the ones we never hear about. We only hear about the successful ones who toiled their way to become what they wanted to become without whining about everything along the way. My limited point is: if you really want to whine, there are much better things to whine about than language/tone of innocuous words in the documentation.
There, where you insult people. It seems clear from the context that you are not including yourself in the snowflakes, instead including yourself as superior to the snowflakes. When someone calls someone else stupid or slow or weak or whiner, it's usually in the context of "and I'm better".
> "get offended by the most random thing imaginable and there is no obligation to cater to everyone's whims and fancies."
Whenever you can split the political divide into compassion/cruelty, it's the Left encouraging or supporting compassion and the right siding with "fuck you, got mine". Who, for example, said you had an 'obligation' to write in a particular way? Instead of the article turning into "yeah, okay, no skin off my nose to remove those words" or "I prefer it this way, feel free to write your own version your way", it turns into namecalling, ego protecting, self-defense.
> "The right, having a meltdown over "just" and "simply": Remove "just" and "simply" else it will ruin my flow of thought"
Saying "X is bad because I trip over it" is not melting down. Saying "you trip over X because you're weak and clumsy and a whining crybaby, you'd never survive an Antartic exploration expedition like a True Scotsman, I have no obligation to do what you demand, I don't need to because I don't trip over X" is. It doesn't engage with the actual issue, doesn't consider whether the change has merit more or less than it costs, doesn't reply about why the style is clearer/better/more fun/more personal, it's a reply to show a) the author is in with the tougher more superior crowd who don't need it, b) the requestor is pathetic.
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.
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...
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 ...".
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.
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.
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.
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.
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.
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.
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.
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.
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 tries to correlate the virtue signal with quality improvement, which is either cringe or disingenuous.
- 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.
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.
I think you might be mad at something different than the principles I'm outlining here. These are accepted standards of technical documentation.
Navel-gazing of the highest order.
I miss Linus Torvald's legendary snark and the epic flame wars of yesteryears.
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.
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.
>> "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.
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.
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.
People rightly deduct style and professionalism points for this regardless of whether they're personally offended.
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.
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.
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.
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
Simple, easy, lightweight - any project with that in the name is a sprawling trashpile.
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.
And 92% of the time, "just" or "simply" have no useful meaning.
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.
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.
Nah, it's fluff. Write good technical documentation, not your wishy-washy feelings about how easy or hard it is.
> Or maybe -- controversial opinion here -- people shouldn't be such babies.
Seriously, why is the top comment using insult disguised as weak rhetorical device ?
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.
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.
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?