Just Simply – Stop saying how simple things are in our docs(justsimply.dev)
justsimply.dev
Just Simply – Stop saying how simple things are in our docs
https://justsimply.dev/
298 comments
Believe me, I am all for people having thicker skins and less entitlement overall. I believe offense is generally taken rather than given, and social media's culture of constant outrage over some thing or another is a form of intellectual and moral decay.
HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They tend towards considering only what they want the reader to do or think, not necessarily who the reader might be or what _they_ want to get out of the writing.
The main problems with the "just simply" writing are twofold:
1. The "just simply" words are completely unnecessary filler. Good writing is stripped of superfluous filler words. Writing with lots of filler words is harder to read because scanning, parsing, and then discarding them is additional cognitive overhead. This technology shit is hard enough as it is, save the flowery prose for your poetry.
2. As others have mentioned, the tone of the "just simply" writing comes off as condescending because it implies the author is considerably more knowledgeable than the reader, that the reader doesn't know anything about the topic at hand, and that the reader will somehow reach enlightenment once they are on the same level as the author.
It's not that I am personally offended by "just simply," it's just bad writing, and I won't read that kind of stuff unless I really have to.
HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They tend towards considering only what they want the reader to do or think, not necessarily who the reader might be or what _they_ want to get out of the writing.
The main problems with the "just simply" writing are twofold:
1. The "just simply" words are completely unnecessary filler. Good writing is stripped of superfluous filler words. Writing with lots of filler words is harder to read because scanning, parsing, and then discarding them is additional cognitive overhead. This technology shit is hard enough as it is, save the flowery prose for your poetry.
2. As others have mentioned, the tone of the "just simply" writing comes off as condescending because it implies the author is considerably more knowledgeable than the reader, that the reader doesn't know anything about the topic at hand, and that the reader will somehow reach enlightenment once they are on the same level as the author.
It's not that I am personally offended by "just simply," it's just bad writing, and I won't read that kind of stuff unless I really have to.
> HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They tend towards considering only what they want the reader to do or think, not necessarily who the reader might be or what _they_ want to get out of the writing.
In my experience - and as a problem on top - writing seems to be one of these crafts in which experience accrues slowly and usually only with good readers.
For example, I've removed "just simply" from my usual documentation vocabulary by just simply following a few steps - sorry, that was too tempting to leave out :) But one realization that drove me away from "simply" was: Simply usually is an imprecise word and this lack of precision opens up doors for misunderstanding. Often when I used simple, I meant it as "simple process" vs "convoluted process". In those cases, I replaced it with "straight-forward" or similar words. This is intended for the reader to judge if they are getting into a process you can just do during a boring meeting, or if they are about to enter some escher-esque rabbit hole.
However, this realization was mostly driven by good readers who informed me about possible misinterpretations my choice of words offers to them. So, even if it sounds nit-picky, go ahead and point out such things and start looking for those. It'll make you a better writer, and other writers around you better.
In my experience - and as a problem on top - writing seems to be one of these crafts in which experience accrues slowly and usually only with good readers.
For example, I've removed "just simply" from my usual documentation vocabulary by just simply following a few steps - sorry, that was too tempting to leave out :) But one realization that drove me away from "simply" was: Simply usually is an imprecise word and this lack of precision opens up doors for misunderstanding. Often when I used simple, I meant it as "simple process" vs "convoluted process". In those cases, I replaced it with "straight-forward" or similar words. This is intended for the reader to judge if they are getting into a process you can just do during a boring meeting, or if they are about to enter some escher-esque rabbit hole.
However, this realization was mostly driven by good readers who informed me about possible misinterpretations my choice of words offers to them. So, even if it sounds nit-picky, go ahead and point out such things and start looking for those. It'll make you a better writer, and other writers around you better.
The best thing I ever did for my writing was subject it to editors and beta readers. It can be hard to find friends who are willing to pick your writing apart, but they're the best kind.
Another way to put this advice on how to write with precision is: carefully consider any use of an adverb in formal writing (pun intended). Most adverbs in formal writing can be replaced by using a better adjective or verb. For some reason, adverbs like "simply" and "quickly" make people feel bad when the process isn't simple or quick, but using words like "straightforward" does not.
Technical writer checking in to cosign everything you've said here. Most style guides advise against this kind of language for the exact reasons you outline—it adds nothing to documentation and it's pithy marketing-speak.
Don't hype up how easy it is to install your product... just tell us how to install the damn thing! :P
> HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with.
Also, completely on point, although in my experience product managers are far worse offenders than engineers.
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.
> the tone of the "just simply" writing comes off as condescending because it implies the author is considerably more knowledgeable than the reader
If the author of some library was not considerably more knowledgeable than myself, then I probably wouldn't be poring over said library's documentation.
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.
Yes, the author of that library knows more about that library. That doesn't mean they are generally more knowledgeable than me, and in fact they may be quite ignorant about the specific problem that lead me to investigate and learn the library in the first place.
But they are writing for an audience that is not as knowledgeable, so “simply” isn’t accurate for the audience, only the writer.
There's room for debate over some of the advice in Elements of Style, but "omit needless words" is a great one that every expository writer should take to heart. The advice to use common words in favor of "fancy vocabulary" is also good.
I agree in general that they're often misused, but "just" and "simply" do have a place. Specifically in place of "only" or "instead", or to set up a subjective comparison.
A: I'm going to do X, Y, and Z.
B: If you just do X, we'll meet the requirements.
A: I tried X Y and Z to fix my problem.
B: You can simply reinstall the IDE.
A: I'm going to do X, Y, and Z.
B: If you just do X, we'll meet the requirements.
A: I tried X Y and Z to fix my problem.
B: You can simply reinstall the IDE.
I think "simply" as a synonym for "instead" is part of the problem here. "Instead" is probably the better option in most cases. For example, in the case you gave, "instead" is the clearer word choice because it clarifies that you are (only) presenting an alternative course of action, rather than offering a value judgement on that action. Similarly, "only" is generally better than "just", because again, it tends to be less loaded and more explicit.
This won't be applicable to all writing - writing for entertainment or to make an argument will look very different - but in technical writing, clarity is key, and words like "just" and "simply" are usually less obvious than their "only" and "instead" counterparts.
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.
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.
It's not the word "simply", it's that if you think every thing that's easy for you is therefore easy, you're communicating that you don't think that understanding other people's experience matters.
The issue often more has to do with how others interpret simply. Someone working in some code base who has some arcane undocumented process and structure to get something functioning or has developed some abstraction over the years may, relative to themselves, think the specific task is "simple." They've lost context of the actual full process and set of abstractions for someone else because they've been so immersed in that space.
For most people working with someone like this directly, that's fine and dandy. I know the process isn't actually simply, I know there's a lack of information, and I know there's a significant hidden time component for someone else to step into that space either if it's me handwaving away complexity or if I'm being handed something that handwaves it away.
The real issue here is that opinions of those people don't matter in terms of the interpretation of complexity. It's the bystanders who don't care about any of the technical pieces. They just want Alice to take over where Bob left off and move on to get the functionality they're paying to get. Bob can gaslight Alice that it simple all day and Alice isn't naive, she knows better.
But business manager Carson is unaware of this and also doesn't care, at all, and when Bob says it's simple while Alice is struggling and Carson starts pressuring Alice like she's an idiot or incapable and Bob steps in and does said task quickly, it looks bad on Alice. If Carson is a good technical leader or manager, they know what's actually going on and Alice may not be incompetent, Bob just has poor documentation or has lost touch with reality. Carson is rarely a good technical manager and has others pressuring them, so you're left with how "simple" something is looking bad on Alice in almost all cases.
This is why developers hate when you handwave away complexity. Do future people a favor and don't pretend something is simple if it's truly not. Think about the entire process you went through to get to the point you are and the set of prerequisite knowledge and patterns you have to do what you're doing. Of course, if you want job security, make Alice and everyone else look bad and keep making everything you do overly complex, vague, and with large gaps of explanation.
For most people working with someone like this directly, that's fine and dandy. I know the process isn't actually simply, I know there's a lack of information, and I know there's a significant hidden time component for someone else to step into that space either if it's me handwaving away complexity or if I'm being handed something that handwaves it away.
The real issue here is that opinions of those people don't matter in terms of the interpretation of complexity. It's the bystanders who don't care about any of the technical pieces. They just want Alice to take over where Bob left off and move on to get the functionality they're paying to get. Bob can gaslight Alice that it simple all day and Alice isn't naive, she knows better.
But business manager Carson is unaware of this and also doesn't care, at all, and when Bob says it's simple while Alice is struggling and Carson starts pressuring Alice like she's an idiot or incapable and Bob steps in and does said task quickly, it looks bad on Alice. If Carson is a good technical leader or manager, they know what's actually going on and Alice may not be incompetent, Bob just has poor documentation or has lost touch with reality. Carson is rarely a good technical manager and has others pressuring them, so you're left with how "simple" something is looking bad on Alice in almost all cases.
This is why developers hate when you handwave away complexity. Do future people a favor and don't pretend something is simple if it's truly not. Think about the entire process you went through to get to the point you are and the set of prerequisite knowledge and patterns you have to do what you're doing. Of course, if you want job security, make Alice and everyone else look bad and keep making everything you do overly complex, vague, and with large gaps of explanation.
Well put, and this harks back to the classic Rich Hickey talk "Simple Made Easy". For Bob the process is easy because he's internalized all the complexity. It's not actually simple. But it's subject to the conflation of "simple" and "easy" that Hickey warned about.
Another way to it has been put is "beginner's mind" or the "curse of knowledge". Once Bob has mastered the many intricate steps it is hard for him to see them clearly and remember the difficulty he himself had. A truly simple process on the other hand would be (relatively) easy for everyone, not just the expert. And of course as you point out it can be difficult for a removed observer to tell the difference.
Another way to it has been put is "beginner's mind" or the "curse of knowledge". Once Bob has mastered the many intricate steps it is hard for him to see them clearly and remember the difficulty he himself had. A truly simple process on the other hand would be (relatively) easy for everyone, not just the expert. And of course as you point out it can be difficult for a removed observer to tell the difference.
This is literally a blog post about not using words like simply, not about reducing complexity or how to share knowledge across progress stages.
Some of us in this thread seem to be taking this blog post to project our past experiences onto, but this post is quite literally just about not using words like simply.
Also nobody will ever take the word literally from me, I will ensure all docs I come across use it bountifully!
Some of us in this thread seem to be taking this blog post to project our past experiences onto, but this post is quite literally just about not using words like simply.
Also nobody will ever take the word literally from me, I will ensure all docs I come across use it bountifully!
connotation exists, you know
It does, generally. However you've failed to demonstrate such enough to remain on topic from what the article is actually saying and to what you posted. So much so I would assume you haven't read the article before you posted.
I read the article, you're refusing to see the forest through the trees.
If you don't understand something then you're in the perfect position to improve the docs. Others who are already familiar with the project may not think they need to document it, because they see it as simple.
This is an important lesson. Anytime you're onboarding a new user/employee, your documentation will benefit by getting that person's feedback. What's incorrect? Where there any steps that weren't clear? Or missing steps? Is there information that's outdated?
I've even gone as far as forcing the developers to answer questions by incorporating new information into the documentation. If you start having out-of-band communication (email, chats, in-person conversations) between the newbie and the team, there's a strong chance that extra information will never find its way back into the documentation.
I've even gone as far as forcing the developers to answer questions by incorporating new information into the documentation. If you start having out-of-band communication (email, chats, in-person conversations) between the newbie and the team, there's a strong chance that extra information will never find its way back into the documentation.
This is such a bizarre take. The post is about removing some unnecessary wording from technical documentation that doesn't add anything, and as an aside can sometimes imply complex tasks are simpler than they are to the detriment of the app/library/service it's documenting. I have no idea why you'd think this implies some personal failing or that it is advice for "babies"
> 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.
I'm not sure that's a fair summary of the article. I just reread it: at no point does it suggest removing superfluous words in general, it's specifically about "words such as easy, painless, straightforward, trivial, simple and just", because those in particular are "jolting", "upsetting and annoying" and "infuriating". What you frame as an "aside" is in fact the first and last paragraph of the article.
> I have no idea why you'd think this implies some personal failing or that it is advice for "babies"
You're missing a level of indirection here, the readers of the documentation are the “babies”, not the writers who take this article's advice. This is advice for people who write for people who act offended when reading the word "simply" in technical documentation, and I'm questioning the dynamics of that.
It's obviously fair to criticize the word choice on my part, there were less incisive ways to phrase that. But then, it's the article that claims that the usage of the word "just" in the sentence (the article's example) "[then] we will just edit the users_controller.rb" is "condescending", and I think that's "simply" (sic) insane.
john lennon once said "never use 'just' in a lyric - it's lazy" (i paraphrase) and i think he might have had simmilar opinions on such things as "trivial". sadly, we will never know.
* He used 'trivialities' in a song (When I Get Home)
* She was "just" seventeen (arguably that was Paul's line, but John didn't override it, and kept his name on it)
* "(Just like) Starting Over" has 'just' in the title and lyrics.
* "Just" gimme some truth.
* "I'm just a jealous guy"
Rules are meant to be broken, perhaps? Or maybe he would just cop to being lazy?
* She was "just" seventeen (arguably that was Paul's line, but John didn't override it, and kept his name on it)
* "(Just like) Starting Over" has 'just' in the title and lyrics.
* "Just" gimme some truth.
* "I'm just a jealous guy"
Rules are meant to be broken, perhaps? Or maybe he would just cop to being lazy?
> Rules are meant to be broken, perhaps? Or maybe he would just cop to being lazy?
both?
the quote i paraphrased was from hunter davies' authorised biog of the beatles
but i still think it is a good rule
both?
the quote i paraphrased was from hunter davies' authorised biog of the beatles
but i still think it is a good rule
i don't completely disagree. I wonder how much of that was a flippant remark, how much his own views changed in the intervening years.
[deleted]
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?
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?
> that doesn't add anything
tbh I enjoy when documentation gives me an idea of the effort required to go trough it. is it just copy pasting commands? does it require any configuration for achieving different goal? am I supposed to handle prerequisites on my own? Is there any passage that require my attention or everything will break down the line?
now, "simple" may not be the correct wording for it, but still I wouldn't say that there's no value in indicating the effort beforehand.
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.
> The post is about
Please reread the comment you are replying to. He’s talking about the hacker news comments.
Please reread the comment you are replying to. He’s talking about the hacker news comments.
The very first sentence of their comment is an appeal to the article. They're addressing the article and using HN comments as evidence to reinforce their perception of it.
"Stop saying how simple things are in our docs"
"Or maybe -- controversial opinion here -- people shouldn't be such babies"
"Stop saying how simple things are in our docs"
"Or maybe -- controversial opinion here -- people shouldn't be such babies"
Yes, it’s possible to alter the meaning of something by quoting a sentence out of context.
If you continue reading to the next sentence, it becomes explicitly clear that he is addressing the comments here.
If you continue reading to the next sentence, it becomes explicitly clear that he is addressing the comments here.
>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.
Looking at example given at this page, before the edit -- it looks like whoever wrote the library is being proud of this little trick they just invented. Look, look, mailer is just another kind of a view! Appreciate how neat it is that we don't invent another high-level concept but reuse existing stuff in a slightly different way. This is personal. Example on the right skips this part and focuses on how to use things.
Being proud of "this little trick we invented" is good ofc, but maybe it's place is in a conference talk or into video of something. Maybe whoever is reading the doc is not your mom and doesn't care right now.
It's a bit of a cultural shift from a community of cool people showing cool stuff to each other to more "it's just a job" kind of attitude. If you aren't there to appreciate clever tricks, it's just noise.
Nah we don’t need to strip out every ounce of personality from something someone was kind enough to write and share for free. Anyone whose delicate sensibilities are so offended can just simply write whatever free library they’re using themselves.
This advice extends far beyond free libraries (and the linked article makes no indication that it's specific to that context). I've encounter all kinds of B2B SaaS docs full of worthless bloat, and I've written docs in the face of pressure from product teams who want to turn documentation into a Look How Cool We Are showcase.
And docs can be clear and straightforward without reading like stereo instructions—you can convey plenty of personality through tone and voice.
And docs can be clear and straightforward without reading like stereo instructions—you can convey plenty of personality through tone and voice.
> people shouldn't be such babies.
Every time I've heard this sentiment in the corporate setting, it sets the ball rolling to create a culture that's hyper masculine and aggressive where people asking for help are seen as weak, unable, and shouldn't be "there". Okay, maybe not fully explicitly, but it influences discussions, how people communicate, and how reviews are laid out over time.
I'd argue that people claiming "people shouldn't be such babies" as the ones needing to be quarantined and separated out from making decisions that impact larger groups of people. It's clear that they can't put themselves in the shoes of others and know how to pull the best out of people.
Every time I've heard this sentiment in the corporate setting, it sets the ball rolling to create a culture that's hyper masculine and aggressive where people asking for help are seen as weak, unable, and shouldn't be "there". Okay, maybe not fully explicitly, but it influences discussions, how people communicate, and how reviews are laid out over time.
I'd argue that people claiming "people shouldn't be such babies" as the ones needing to be quarantined and separated out from making decisions that impact larger groups of people. It's clear that they can't put themselves in the shoes of others and know how to pull the best out of people.
I dont know about taking it personally, but it is very annoying to me. It is also misleading, because most of the times it is not simple by most definitions. I like my documentation to be concise and give me information, not make effort estimates for me :D. I know it's a silly point, but it is very grating to read. I would file this under bad writing practice.
[deleted]
I could tell you you're missing the obvious answer, but that doesn't help you understand the thing you're missing. I could tell you the YouTube tutorial that starts from scratch has a very simple and obvious reason why it starts there, that a lot of other people get that you don't. But that doesn't help you either. And I could tell you that infantilizing someone who's having a hard time understanding something is the opposite of adult, but that doesn't tell you why.
> YouTube tutorial that starts from scratch has a very simple and obvious reason why it starts there
what's the reason in your opinion?
Because in my opinion a programming tutorial that starts from installibg the IDE is like a recipe tutorial that starts from how to use a gas stove.
it should be two different tutorials, at least
It is clearly important to understand how an IDE works, but that's the kind of knowledge that should be implied when you watch a programming tutorial.
Otherwise you need to learn two things at the same time.
Besides, IDE are usually complex enough that the two sets of skill don't overlap, so if the tutorial focuses on the programming and skims over installing the IDE, it is assuming that you can "simply" or "trivially" install an IDE such as Jetbrains Idea and be immediately ready to use it proficiently enough to learn something else with it, instead of fighting it to get things done. Which is usually the case, when I teach programming at work I focus on the programming using slides or some basic live coding using a very basic editor (vanilla sublime for example), because if I start using IDE features, people start making a lot of questions on how to do the things that I am doing that I don't even realize that I am doing them without even thinking about them, to the point that it becomes an IDE focused training. Showing that you can't take for granted that installing an IDE is a good starting point. It raises more issues than it solves.
I'm quite sure it would have been much harder for me to study Italian literature while I was learning how to read.
what's the reason in your opinion?
Because in my opinion a programming tutorial that starts from installibg the IDE is like a recipe tutorial that starts from how to use a gas stove.
it should be two different tutorials, at least
It is clearly important to understand how an IDE works, but that's the kind of knowledge that should be implied when you watch a programming tutorial.
Otherwise you need to learn two things at the same time.
Besides, IDE are usually complex enough that the two sets of skill don't overlap, so if the tutorial focuses on the programming and skims over installing the IDE, it is assuming that you can "simply" or "trivially" install an IDE such as Jetbrains Idea and be immediately ready to use it proficiently enough to learn something else with it, instead of fighting it to get things done. Which is usually the case, when I teach programming at work I focus on the programming using slides or some basic live coding using a very basic editor (vanilla sublime for example), because if I start using IDE features, people start making a lot of questions on how to do the things that I am doing that I don't even realize that I am doing them without even thinking about them, to the point that it becomes an IDE focused training. Showing that you can't take for granted that installing an IDE is a good starting point. It raises more issues than it solves.
I'm quite sure it would have been much harder for me to study Italian literature while I was learning how to read.
One of the things I do for a living is write documentation. I have the privilege of supporting a lot of different types of users. And within each type of user, there is variability.
For every document I write, there are always a couple people for whom my document fails. It's not because they're stupid, or because I am. It's because communication is hard, and different perspectives change how information is processed. In addition, in many cases, there's simply a different use case that my document didn't account for because I didn't think of it or run into it.
So much of the time, I need to amend documents after the fact. I may need to clarify a statement, or provide alternate instructions. Often it's a detail that I thought should be universal but wasn't. And often users will simply have done something different beforehand, or out of order, or in some way not in accordance with the intended instructions.
Therefore, if I want a user to be successful with my document, it has to be complete, and thorough, and be tested by different people. It needs to not make assumptions, and it needs to be clear and concise so it can be followed in one go.
If you start getting fancy and make 50 different documents for different steps, because "logically" that makes more sense, what you will find is the user will run into a problem that the two separate documents didn't consider when taken together. Then the user will stop and try to find someone to fix their issue.
If you don't want to be tied up in support calls your whole life, one complete document is the best solution. And if you're a user who just wants to try out some sample tutorial, one complete document is the most likely to work for you without taking up more of your time.
The YouTube video that shows you installing the IDE is superior to one that doesn't. And for pete's sake you can always skip through it.
For every document I write, there are always a couple people for whom my document fails. It's not because they're stupid, or because I am. It's because communication is hard, and different perspectives change how information is processed. In addition, in many cases, there's simply a different use case that my document didn't account for because I didn't think of it or run into it.
So much of the time, I need to amend documents after the fact. I may need to clarify a statement, or provide alternate instructions. Often it's a detail that I thought should be universal but wasn't. And often users will simply have done something different beforehand, or out of order, or in some way not in accordance with the intended instructions.
Therefore, if I want a user to be successful with my document, it has to be complete, and thorough, and be tested by different people. It needs to not make assumptions, and it needs to be clear and concise so it can be followed in one go.
If you start getting fancy and make 50 different documents for different steps, because "logically" that makes more sense, what you will find is the user will run into a problem that the two separate documents didn't consider when taken together. Then the user will stop and try to find someone to fix their issue.
If you don't want to be tied up in support calls your whole life, one complete document is the best solution. And if you're a user who just wants to try out some sample tutorial, one complete document is the most likely to work for you without taking up more of your time.
The YouTube video that shows you installing the IDE is superior to one that doesn't. And for pete's sake you can always skip through it.
> The YouTube video that shows you installing the IDE is superior to one that doesn't
I disagree.
That's assuming that your time is infinite, the user time is infinite and you are writing a tutorial about everything.
It's usually not the case, the best documentation I have found is the kind that focus on what it is about and only that.
It doesn't imply that an introduction is not necessary, it implies that you will talk about what's in the title of the document and only that. You have to assume a certain level of knowledge, you gotta stop somewhere and say "they must know this already or this is not for them" otherwise any documentation should include a chapter on how to download the software you are about to install and how to, why not?, connect to a WI-FI network. "A tutorial that talks about it is superior to one that doesn't" isn't it?
YouTube videos do that because the algorithm rewards longer videos, tech writers to that because it makes the final document larger and larger is always better than smaller, if you are paid for the words you write.
The laziest documentation I have found is the one that starts from the origin of the universe and it only resolves in the last 5 paragraphs, "drawing an howl" style, even though it should only be about drawing the damn howl.
One infamous example is Coursera coursers, each one of them presents the same exact intros, like if it's Java or Scala, they start on how to install Intellij Idea and the first assignment is compile a project and send it to show you understood how it is done. Except the course is called something like "Writing highly concurrent distributed systems in Scala", it is marked as an advanced specialization and it makes no sense to take it if you don't know how to install an IDE. But even assuming it happens, it could be easily solved by an FAQ. And BTW you have to complete the first assignment even if this is the nth course you're taking on the subject, you already installed Intellij, already compiled a project and already completed the assignment n minus 1 other times.
Do you also believe that teaching people how to drive a car should start from how to buy one?
> what you will find is the user will run into a problem that the two separate documents didn't consider when taken together.
the opposite is usually true in my experience.
You will find that most of the times the people that are actually interested in the documentation, will be much better off with a more succinct version of the same document.
> If you start getting fancy and make 50 different documents for different steps, because "logically" that makes more sense,
Nobody said 50 different documents. Just separated the "tools setup" from the rest of the documentation or put it in an appendices at the end.
The "setup" section in most Github repos are very welcome, if they are in the in the form
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 ...`
I dont think its personal, at least it isn't for me. Its because it is wrong. If it is documentation intended for people new to this its better to explain everything, and avoid making assumptions about what is simple or not. Its so much better to just have documentation of everything or to refer to it.
I don’t think “offended” is a fair assessment of how people react to these types of filler words. I think we tend to forget, especially after reading and writing computer languages, that our human languages are meant to be read and understood by other humans and our words can have a powerful effect on others. As the blog post suggests, this does seem to come out of a place of excitement to share knowledge, but it can come across as off-putting or disingenuous if, for example, something described as “simple” is not. Regardless of how fragile others are and conversely how tough you think you are, we are all affected by the way things are worded, with each of us carrying our own baggage and differing understanding of specific connotations. This is, however, not about adding bumpers to our language so that nobody feels hurt, it’s about communicating concepts and instructions in universally clear language that is not muddied with fluff or superlatives. In other words, it’s a UX problem.
For the record, I don’t disagree that people seem to be offended easily. Often the least charitable meaning is assumed and people escalate/react accordingly. Many individuals have become trained to fixate so heavily on micro aggressions that the context and tone of messages is lost and these people become difficult to interact with and a cycle of misery ensues where they find themselves surrounded by people who only walk on eggshells when communicating.
For the record, I don’t disagree that people seem to be offended easily. Often the least charitable meaning is assumed and people escalate/react accordingly. Many individuals have become trained to fixate so heavily on micro aggressions that the context and tone of messages is lost and these people become difficult to interact with and a cycle of misery ensues where they find themselves surrounded by people who only walk on eggshells when communicating.
It's unfortunate that this is the top comment, because the "after" samples are clear improvements.
This is good old-fashioned writing advice, no different from Strunk and White's "Omit needless words" -- just tailored to developer documentation where a handful of specific needless words flourish.
The main reason to remove these words is that they are fluffy, superfluous marketing speak.
Do some people also find them condescending? Maybe -- I don't, but this is a side point.
This is good old-fashioned writing advice, no different from Strunk and White's "Omit needless words" -- just tailored to developer documentation where a handful of specific needless words flourish.
The main reason to remove these words is that they are fluffy, superfluous marketing speak.
Do some people also find them condescending? Maybe -- I don't, but this is a side point.
It's an improvement because it cut out all the adverbs. The tone of the essay is an unmistakable virtue signal.
It tries to correlate the virtue signal with quality improvement, which is either cringe or disingenuous.
It tries to correlate the virtue signal with quality improvement, which is either cringe or disingenuous.
Completely disagree that this is a form of virtue signaling; everything the article outlines is reflected in the major documentation style guides (e.g., MMoS or the Google developer documentation style guide).
- Don't make unsubstantiated claims about your product.
- Don't discuss upcoming features or refer to existing features as "new" outside of announcements/release notes.
- Don't make promises about uptime or other things that belong in an SLA—this can have nasty legal implications down the line.
- Don't waste time with marketing-speak; your reader is either already using your product or is on the verge of using your product (and consulting the quality of your docs before they decide to move forward).
- Don't use ambiguous language or cultural idioms that may confuse ESL readers.
- Don't preface instructions with how easy it is to do something; every reader has a different level of experience and background knowledge. Also, if you say that your product is easy to use and then it actually isn't, it makes you look like an idiot. Or disingenuous. Or both.
- Don't make unsubstantiated claims about your product.
- Don't discuss upcoming features or refer to existing features as "new" outside of announcements/release notes.
- Don't make promises about uptime or other things that belong in an SLA—this can have nasty legal implications down the line.
- Don't waste time with marketing-speak; your reader is either already using your product or is on the verge of using your product (and consulting the quality of your docs before they decide to move forward).
- Don't use ambiguous language or cultural idioms that may confuse ESL readers.
- Don't preface instructions with how easy it is to do something; every reader has a different level of experience and background knowledge. Also, if you say that your product is easy to use and then it actually isn't, it makes you look like an idiot. Or disingenuous. Or both.
If you completely disagree, keep in mind “completely” is also an adverb.
Some frameworks sell simplicity (setup, maintenance) as a feature, so that adverb would be fitting.
But this is just infantilizing and a lot of people (maybe a universal trait) are annoyed by that.
Some frameworks sell simplicity (setup, maintenance) as a feature, so that adverb would be fitting.
But this is just infantilizing and a lot of people (maybe a universal trait) are annoyed by that.
What? Adverbs are fine; there's no industry-wide dictum against adverbs.
I think you might be mad at something different than the principles I'm outlining here. These are accepted standards of technical documentation.
I think you might be mad at something different than the principles I'm outlining here. These are accepted standards of technical documentation.
This is basic English grammar, something you should have learned in grade school.
Your grade school taught you that adverbs are a form of virtue signaling?
No one will fall apart and burst into tears because of an adverb they read in the mountain of documentation we have to read to get the job done.
Navel-gazing of the highest order.
Navel-gazing of the highest order.
You lost me there again, my friend. Technical writing stylebooks draw no correlation between adverbs and nervous breakdowns. You seem to be tilting at an entirely different windmill than the one I'm tending to.
That's fine, but put your marketing copy in your marketing, not in your docs.
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.
It’s noise not unlike those 1-hour long “Shopping TV” ads.
I’m not against using the word as ling as it’s put into some kind of framework which allows some actual assessment of these claims:
— Simple compared to what?
— What prior knowledge or skill is assumed?
— When does it stop being simple?
But since “simple” is being either used by authors deeply enamored with their brainchild, or as I said above, as a marketing (read: manipulation) tool, your chances of getting straight answerd are slim.
> Why is this so personal?
It's simple to understand, really. How come you don't get this trivial thing?
It's simple to understand, really. How come you don't get this trivial thing?
> Is that the reason why tech documentation has slowly been evolving into 50-minute step-by-step YouTube tutorials that start with installing the IDE? What happened to the expectation of people being adults?
I think this really proves that writing good documentation is a skill you can hone.
In my opinion, if you're writing a package, gem, etc. for a web framework:
Having extremely concise documentation where you assume the person using your tool is already an expert, so you skip everything except for the precise details related to your tool can be frustrating for anyone looking to use your package unless they happen to be at a skill level where they could have written the package themselves. If folks can't figure out how to use your tool, they'll use something else.
Having extremely verbose documentation to the point where you rewind things back to installing an IDE or explaining what a for loop is for an extension related to pagination is equally as frustrating for most folks because they already have the basics down and want to figure out how to use your package.
I'm a firm believer that good documentation for such a tool or package would include the "why" with a few practical examples along with a guide-like approach of explaining how to get it to work where you use title headings and bullets to make it skimmable as a reference at the same time. You can still make it concise while covering all of that ground. I see nothing wrong with having both text and video.
This way you satisfy a wide range of skill levels without frustrating or alienating anyone. This approach isn't coming at it from an angle to "protect" anyone either. It's optimizing for general success where success is defined as anyone other than yourself can use the package with minimal'ish friction.
I think this really proves that writing good documentation is a skill you can hone.
In my opinion, if you're writing a package, gem, etc. for a web framework:
Having extremely concise documentation where you assume the person using your tool is already an expert, so you skip everything except for the precise details related to your tool can be frustrating for anyone looking to use your package unless they happen to be at a skill level where they could have written the package themselves. If folks can't figure out how to use your tool, they'll use something else.
Having extremely verbose documentation to the point where you rewind things back to installing an IDE or explaining what a for loop is for an extension related to pagination is equally as frustrating for most folks because they already have the basics down and want to figure out how to use your package.
I'm a firm believer that good documentation for such a tool or package would include the "why" with a few practical examples along with a guide-like approach of explaining how to get it to work where you use title headings and bullets to make it skimmable as a reference at the same time. You can still make it concise while covering all of that ground. I see nothing wrong with having both text and video.
This way you satisfy a wide range of skill levels without frustrating or alienating anyone. This approach isn't coming at it from an angle to "protect" anyone either. It's optimizing for general success where success is defined as anyone other than yourself can use the package with minimal'ish friction.
I agree with your point. Nowadays, people seem to be overly sensitive about their code and the way we communicate, among other things.
It's important to remember that the code is not a reflection of ourselves, and not everyone will be pleased with it. Some will provide good guidance, while others will not. Therefore, we should remove our ego from the code. Code is like a lollipop that we enjoy, but then discard once we're done with it.
If I don't understand a design doc, it doesn't necessarily mean that I'm stupid or that the writer is bad at communicating. It may simply require more effort on my part to fully comprehend it.
I don't understand why some people are so sensitive and take everything as a personal attack.
It's important to remember that the code is not a reflection of ourselves, and not everyone will be pleased with it. Some will provide good guidance, while others will not. Therefore, we should remove our ego from the code. Code is like a lollipop that we enjoy, but then discard once we're done with it.
If I don't understand a design doc, it doesn't necessarily mean that I'm stupid or that the writer is bad at communicating. It may simply require more effort on my part to fully comprehend it.
I don't understand why some people are so sensitive and take everything as a personal attack.
> Nowadays, people seem to be overly sensitive about their code and the way we communicate, among other things.
If there's one thing I've learned in life, anytime you see "Nowadays" or "these days" or something similar, you can be guaranteed that whatever statement follows it is a universal truism about the human condition that recency has no bearing on.
People are sensitive about their work. And sensitive to how we communicate together. Always have been. Always will be.
If there's one thing I've learned in life, anytime you see "Nowadays" or "these days" or something similar, you can be guaranteed that whatever statement follows it is a universal truism about the human condition that recency has no bearing on.
People are sensitive about their work. And sensitive to how we communicate together. Always have been. Always will be.
So you're saying people as a whole don't change behavior over time?
It's not possible that the average modern software developer is just a bit more sensitive about their work than a welder was in 1950?
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?
> So you're saying people as a whole don't change behavior over time?
At a fundamental emotional level, yea that's pretty much what I am saying.
> It's not possible that the average modern software developer is just a bit more sensitive about their work than a welder was in 1950?
Maybe. It's possible that the selection of 1950s welders consisted of a fundamentally different slice of the overall social profile than coders of the 2020s. But overall sensitivity comes with pride. If 1950s welders had pride in their work I am certain they had sensitivity about it also.
But the statement was "Nowadays people seem to be oversensitive about their code". So you have to compare people who write code now vs people who wrote code in the past. Not two different professions.
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.
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.
People, in general, are sensitive about anything important to them.
I was trying to compare equivalent professions across time periods, not to suggest that welders are any different than developers.
I would not be surprised if modern day welders get offended by their equipment manual as well.
I would not be surprised if modern day welders get offended by their equipment manual as well.
I A. Don't see significant similarity between welding and programming B. Think that you would be wrong about people being annoyed about things that make their work harder across any time period.
The difference is how people expressed those emotions or not, not whether they had them.
The difference is how people expressed those emotions or not, not whether they had them.
> The difference is how people expressed those emotions or not
That's a change in behavior.
That's a change in behavior.
> It's not possible that the average modern software developer is just a bit more sensitive about their work than a welder was in 1950?
I was responding to this. My answer is no. Whether they express it or not, I imagine the sensitivity hasn't increased. You can feel something (being sensitive) without choosing to express it.
Emotional control is something well-adjusted people do every day, regardless of what they are feeling. It is simply more acceptable to express these emotions now.
If I had to guess people in the 50s just died inside and then drank themselves to death instead. Or took it out on their families.
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.
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.
Further, we’re adults, as you say, so let’s be adults and take the time to consider our readers position and how our writing might be interpreted. You’re doing no one any favors by refusing to be empathetic.
I've never heard of anyone quitting because they objected to being told something which they find complicated is "simple," so this seems like a straw man.
I think a lot of people think about how best to teach complicated ideas. Maybe like me, they really aren't that smart, or even just feel like they aren't that smart, and when they read from an expert or an instructor or a professor that a thing is simple, that voice inside their head that is constantly telling them they're dumb or worthless gets louder, and they wonder if that vouce is right, and that the idea they are trying to understand is simple for people who aren't impostors and they should probably give up and shoot themselves.
Your professor used the word "trivially" in a stupid way. Similarly, technical writers and instructors use "simple" in a stupid way. Objecting to stupid language from teachers and technical writers that makes them less effective at their jobs doesn't make me a baby any more than celebrating it makes you an adult.
I don't think people who use words like this intend for their audience to feel stupid. But I don't see how they are helpful.
I think a lot of people think about how best to teach complicated ideas. Maybe like me, they really aren't that smart, or even just feel like they aren't that smart, and when they read from an expert or an instructor or a professor that a thing is simple, that voice inside their head that is constantly telling them they're dumb or worthless gets louder, and they wonder if that vouce is right, and that the idea they are trying to understand is simple for people who aren't impostors and they should probably give up and shoot themselves.
Your professor used the word "trivially" in a stupid way. Similarly, technical writers and instructors use "simple" in a stupid way. Objecting to stupid language from teachers and technical writers that makes them less effective at their jobs doesn't make me a baby any more than celebrating it makes you an adult.
I don't think people who use words like this intend for their audience to feel stupid. But I don't see how they are helpful.
"Simple" reads "simple for me" (the author). That can be really frustrating at times.
But the real sin here is wasting words on useless bullshit. Just get to the damned point. "Just simply" is 100% waste. I can replace "Just simply verb" with "verb" and the sentence is already better, without putting a bunch of emotional loading into the context of the discussion.
But the real sin here is wasting words on useless bullshit. Just get to the damned point. "Just simply" is 100% waste. I can replace "Just simply verb" with "verb" and the sentence is already better, without putting a bunch of emotional loading into the context of the discussion.
Part of article about "sharing excitement" I would rewrite:
Stop writing "it is easy - just do x" because it is plain marketing bullshit that people are compelled to add to documentation or website describing library/tool only for a reason that - they think they should do it.
Stop writing "it is easy - just do x" because it is plain marketing bullshit that people are compelled to add to documentation or website describing library/tool only for a reason that - they think they should do it.
> What happened to the expectation of people being adults?
The below quotes from Haidt summarize the concept that culture at large is promoting an inverse of CBT. As a result the knowledge increasing method of criticism has been hijacked by folx channeling their inner Foucault.
CBT (Cognitive Behavioral Therapy). In CBT you learn to recognize when your ruminations and automatic thinking patterns exemplify one or more of about a dozen “cognitive distortions,” such as catastrophizing, black-and-white thinking, fortune telling, or emotional reasoning.
. . .
Greg hypothesized that if colleges supported the use of these cognitive distortions, rather than teaching students skills of critical thinking (which is basically what CBT is), then this could cause students to become depressed. Greg feared that colleges were performing reverse CBT.
https://jonathanhaidt.substack.com/p/mental-health-liberal-g...
The below quotes from Haidt summarize the concept that culture at large is promoting an inverse of CBT. As a result the knowledge increasing method of criticism has been hijacked by folx channeling their inner Foucault.
CBT (Cognitive Behavioral Therapy). In CBT you learn to recognize when your ruminations and automatic thinking patterns exemplify one or more of about a dozen “cognitive distortions,” such as catastrophizing, black-and-white thinking, fortune telling, or emotional reasoning.
. . .
Greg hypothesized that if colleges supported the use of these cognitive distortions, rather than teaching students skills of critical thinking (which is basically what CBT is), then this could cause students to become depressed. Greg feared that colleges were performing reverse CBT.
https://jonathanhaidt.substack.com/p/mental-health-liberal-g...
When I read the OP's example rewrite ("Calling the Mailer") I find his rewrite to be far less patronizing than the original.
Ironically, the original one -- with all of the supposedly "offensive" copy -- reads like it was meant for babies.
I'm not offended by that, it's just annoying and distracting. His rewrite is remarkably better.
Ironically, the original one -- with all of the supposedly "offensive" copy -- reads like it was meant for babies.
I'm not offended by that, it's just annoying and distracting. His rewrite is remarkably better.
At best, "trivial", "just", "simply" are all noise words. They add no context.
At worst they are targeted at the wrong audience. The writer doesn't actually know how knowledgeable or experienced the reader is.
So if you're a writer or you're simply (heh) writing docs for a library you're working on, and you're decent at this task so you take a moment to reflect on how your audience might read your writing, why would you use the word at all?
> is that the reason why tech documentation has slowly been evolving into 50-minute step-by-step YouTube tutorials that start with installing the IDE?
Instead of falling into the trap of "kids these days" short-sighted whining, perhaps consider that the barriers to creating and sharing content have never been lower. More content targeted at beginners seems like a natural conclusion to me, since it reaches the widest audience.
At worst they are targeted at the wrong audience. The writer doesn't actually know how knowledgeable or experienced the reader is.
So if you're a writer or you're simply (heh) writing docs for a library you're working on, and you're decent at this task so you take a moment to reflect on how your audience might read your writing, why would you use the word at all?
> is that the reason why tech documentation has slowly been evolving into 50-minute step-by-step YouTube tutorials that start with installing the IDE?
Instead of falling into the trap of "kids these days" short-sighted whining, perhaps consider that the barriers to creating and sharing content have never been lower. More content targeted at beginners seems like a natural conclusion to me, since it reaches the widest audience.
> Similarly, when documentation mentions to "simply" do something, and I don't get it, isn't that a clear hint that I'm still missing a concept somewhere and need to look around for an explanation?
Nah, it's fluff. Write good technical documentation, not your wishy-washy feelings about how easy or hard it is.
edit: write like you'd write an RFC.
> Or maybe -- controversial opinion here -- people shouldn't be such babies.
Seriously, why is the introduction of the top comment a thinly veiled insult disguised as a weak rhetorical device ?
Nah, it's fluff. Write good technical documentation, not your wishy-washy feelings about how easy or hard it is.
edit: write like you'd write an RFC.
> Or maybe -- controversial opinion here -- people shouldn't be such babies.
Seriously, why is the introduction of the top comment a thinly veiled insult disguised as a weak rhetorical device ?
The opposite view of what you criticize is the Stockholm syndromey "documentation is for losers" where you should "just read C-headers for how to interface, or the actual library code to figure out what the library does". In this view, asking for help or admitting to not knowing or understanding something is a sign of weakness and incompetence. Thus, people who ask questions aren't worth a competent™ person's time.
My view: the purpose of documentation is to help people achieve their goals using your tools. Do everything that helps this purpose and don't do things that don't help it.
Does the occasional "simply" help the purpose? I would say it almost never does. Telling users whether a step is simple is meta-commentary that distracts from the actual steps and is only useful if it helps people make decisions ("choose way X to do Y because it's simple"). People who sprinkle "simply" into documentation seem to rarely think about whether it serves a real purpose.
50-minute step-by-step tutorials are very useful when your goal is just to do that thing. This conforms to my view that tutorials and documentation serve the purpose of allowing people to achieve goals.
You might feel instead that there should also be some pedagogical goal. People who read your documentation should become smarter, think outside the box, learn patience and perseverance that is required for their craft, etc.
I think the real debate here is about this fundamental distinction of what purpose documentation serves.
My view: the purpose of documentation is to help people achieve their goals using your tools. Do everything that helps this purpose and don't do things that don't help it.
Does the occasional "simply" help the purpose? I would say it almost never does. Telling users whether a step is simple is meta-commentary that distracts from the actual steps and is only useful if it helps people make decisions ("choose way X to do Y because it's simple"). People who sprinkle "simply" into documentation seem to rarely think about whether it serves a real purpose.
50-minute step-by-step tutorials are very useful when your goal is just to do that thing. This conforms to my view that tutorials and documentation serve the purpose of allowing people to achieve goals.
You might feel instead that there should also be some pedagogical goal. People who read your documentation should become smarter, think outside the box, learn patience and perseverance that is required for their craft, etc.
I think the real debate here is about this fundamental distinction of what purpose documentation serves.
I completely empathize with this sentiment and understand where you're coming from. However, I've been writing tutorials and documentation for awhile now, and while editing my videos I realized that I would often say "see, simple" after explaining a topic (which is equivalent to just simply in my opinion). I realized that 99% of the time I said that, it was filler and unnecessary, almost like a nervous tick.
Aside from that, of course it's simple for me! I'm the one writing the documentation or creating the tutorial. I've tried to simplify the material into digestible steps. However, this also means I know the subject at hand inside and out. My target audience doesn't necessarily know it as well as me.
So, instead of saying, "see simple" in my tutorials, I began asking myself, "is this concept truly simple for my target audience?" If it isn't simple, then that points out an area I need to clarify and simplify further. I only consider the video/documentation done when I can truly say to myself that the technical content is concise and simple enough for my target audience. This leads to better technical writing (no unnecessary filler), and it leads to a hopefully thoroughly thought out description of the material at hand.
So I don't believe people are being babies or shamed into quitting their careers over a misplaced "simply". Rather, I think they're subconsciously understanding that the writer of the documentation wasn't ruthlessly cutting down the material. I think "just simply" often points to lazy writing, and people pick up on that. Good documentation is ruthlessly concise, truly simple (as in its reduced to the smallest piece of information possible), and it conveys the necessary information quickly.
Aside from that, of course it's simple for me! I'm the one writing the documentation or creating the tutorial. I've tried to simplify the material into digestible steps. However, this also means I know the subject at hand inside and out. My target audience doesn't necessarily know it as well as me.
So, instead of saying, "see simple" in my tutorials, I began asking myself, "is this concept truly simple for my target audience?" If it isn't simple, then that points out an area I need to clarify and simplify further. I only consider the video/documentation done when I can truly say to myself that the technical content is concise and simple enough for my target audience. This leads to better technical writing (no unnecessary filler), and it leads to a hopefully thoroughly thought out description of the material at hand.
So I don't believe people are being babies or shamed into quitting their careers over a misplaced "simply". Rather, I think they're subconsciously understanding that the writer of the documentation wasn't ruthlessly cutting down the material. I think "just simply" often points to lazy writing, and people pick up on that. Good documentation is ruthlessly concise, truly simple (as in its reduced to the smallest piece of information possible), and it conveys the necessary information quickly.
First of all, you're exaggerating tremendously, as I don't see anybody "quitting their career" over documentation, and literally nobody is talking about impostor syndrome (in the article or comments here). You're seeing things that aren't there.
But secondly, I think what you're writing is a great example of how their are two philosophies or ideologies of communication.
One philosophy (that you seem to subscribe to) is that it's the prerogative of the speaker (writer) to communicate however they think is right, and it's the responsibility of the listener (reader) to do the work to understand it, and reponsibility for miscommunication lies with the listener. To use your words, the speaker doesn't need to "baby" the listener, and the listener is wrong to be "personally offended".
But the other philosophy is that it's the responsibility of the speaker to communicate in a way that will be best understood, and it's the prerogative of the listener to note where the speaker's communication is unclear, misleading, frustrating, or offensive to the listener. It's the speaker's job to make a good faith effort to know their audience and communicate appropriately for that audience, and to apologize and rephrase when they make mistakes.
Now, which one is right? Well, there is no "right". What there is is -- which one serves you better as the speaker? Which philosophy will further your goals, which one will get you further in life?
Well if your goal is to be able to get angry at listeners/readers who don't get it and feel smarter than others, by all means adopt the first philosophy. But if your goal is for your speech and writing to have the impact you want it to have, the second philosophy is going to be more productive for you. And calling people "babies" is about as counterproductive as you can be in terms of getting people to listen to you.
But secondly, I think what you're writing is a great example of how their are two philosophies or ideologies of communication.
One philosophy (that you seem to subscribe to) is that it's the prerogative of the speaker (writer) to communicate however they think is right, and it's the responsibility of the listener (reader) to do the work to understand it, and reponsibility for miscommunication lies with the listener. To use your words, the speaker doesn't need to "baby" the listener, and the listener is wrong to be "personally offended".
But the other philosophy is that it's the responsibility of the speaker to communicate in a way that will be best understood, and it's the prerogative of the listener to note where the speaker's communication is unclear, misleading, frustrating, or offensive to the listener. It's the speaker's job to make a good faith effort to know their audience and communicate appropriately for that audience, and to apologize and rephrase when they make mistakes.
Now, which one is right? Well, there is no "right". What there is is -- which one serves you better as the speaker? Which philosophy will further your goals, which one will get you further in life?
Well if your goal is to be able to get angry at listeners/readers who don't get it and feel smarter than others, by all means adopt the first philosophy. But if your goal is for your speech and writing to have the impact you want it to have, the second philosophy is going to be more productive for you. And calling people "babies" is about as counterproductive as you can be in terms of getting people to listen to you.
This is a useful framing, and personally I learn hard toward the "speaker is responsible" strategy.
With that said, I think a continuum is an even more accurate framing. If you are confusing your audience, it is probably your fault. But not necessarily. Some people won't make an effort, will be distracted, or will engage in bad faith. I see it as a negotiation in which you should be strongly biased toward the audience being right.
With that said, I think a continuum is an even more accurate framing. If you are confusing your audience, it is probably your fault. But not necessarily. Some people won't make an effort, will be distracted, or will engage in bad faith. I see it as a negotiation in which you should be strongly biased toward the audience being right.
Nailed it.
You got me thinking with your "two ideologies"... I think it's more accurate to say, there are different modes of communication with different goals. At a minimum, there's sharing information, entertaining, social signalling, fighting/arguing. The relationship between speaker and listener varies in each case. Vocabulary, turn of phrase, tone all contribute. It's wise to figure out which case you're in and adjust accordingly.
You got me thinking with your "two ideologies"... I think it's more accurate to say, there are different modes of communication with different goals. At a minimum, there's sharing information, entertaining, social signalling, fighting/arguing. The relationship between speaker and listener varies in each case. Vocabulary, turn of phrase, tone all contribute. It's wise to figure out which case you're in and adjust accordingly.
Newbies get into loops by thinking the solution is simple when it's complex from their perspective and can go off rabit paths and waste time. Kind of like the opposite of overthinking a solution when the solution is simple. It's a writing linter.
I suppose it depends whether you’re writing documentation that you want people to read or not.
I often have to write documentation for non-technical people, and if they don’t understand it or they find it too discouraging to follow, it makes my job harder.
I can yell and shout all day about how they should just get a thicker skin and study my words more thoroughly, but it won’t change human nature. Eventually you need to stop wishing humanity was different, and accept humanity as it is.
I often have to write documentation for non-technical people, and if they don’t understand it or they find it too discouraging to follow, it makes my job harder.
I can yell and shout all day about how they should just get a thicker skin and study my words more thoroughly, but it won’t change human nature. Eventually you need to stop wishing humanity was different, and accept humanity as it is.
It's not that the inclusion of this one word is offensive and so the entire product is ruined. It's a matter of accessibility. The more of it (accessibility) your thing has, the more accessible the thing is.
Why add something to your product that some users find makes their time with your product worse? If there is little to no reason[0] to include a feature and removing it could help some users, then not including it or removing it is a no-brainer.
> One month in,
If it took you a month, it sounds like it wasn't trivial. As presented, it sounds like your prof saying that was pointless at least.
[0] In this case, it's hard to see any benefit at all from adding the "simply ...".
Why add something to your product that some users find makes their time with your product worse? If there is little to no reason[0] to include a feature and removing it could help some users, then not including it or removing it is a no-brainer.
> One month in,
If it took you a month, it sounds like it wasn't trivial. As presented, it sounds like your prof saying that was pointless at least.
[0] In this case, it's hard to see any benefit at all from adding the "simply ...".
The thing is, even if the "simple" thing is indeed simple, why write it down? It is most likely a useless word and your writing will be clearer without it. There is a good example in the article.
This is something editors will tell you, be it for fiction or for technical writing: make every word count, remove the fluff.
As for "trivial" in math proofs, knowing how codified math is, I guess there is a precise use case for it. But I don't usually see math proofs telling me that "2+2=4" is trivial, they just write "4", and that's what the article suggests.
This is something editors will tell you, be it for fiction or for technical writing: make every word count, remove the fluff.
As for "trivial" in math proofs, knowing how codified math is, I guess there is a precise use case for it. But I don't usually see math proofs telling me that "2+2=4" is trivial, they just write "4", and that's what the article suggests.
Resilience and good communication don't share an axis. You can want and have both. To me, the examples in the article make a convincing case for what's stronger writing and that's good enough.
One of the rare times where I agree that someone being infuriated by these words is a bit ridiculous. It's not like they're offensive or emotionally manipulative, it's merely a matter of someone's style of writing or just a means of encouraging someone to do the task that might otherwise seem daunting by virtue of being one of a hundred tasks they have to do that day. It can be annoying but complaining about hyperbolic words and then saying they are "infuriating" is a tad ironic.
I like your perspective in general. The reason I don’t mind getting a little bit worked up about it is because most documentation is terrible and that can make people frustrated and feel bad when it doesn’t have to. Which plays into your point, but spreading this over thousands, or millions of users seems like a terribly unproductive strategy. If you correct the documentation, once you will make many people's experience better over the life of the documentation.
I am on the same page, for whatever reason everyone is fragile now, and we need to make all efforts to avoid breaking things into thousands of broken glass pieces.
This whole feel good censorship feels no different from the old days, when my previous generation had to measure every single word, not that PIDE/DGS were going to be made aware of it.
This whole feel good censorship feels no different from the old days, when my previous generation had to measure every single word, not that PIDE/DGS were going to be made aware of it.
More controversial opinion is that there's too much ego-stroking fluff in general and everything is "perfect" and "elegant" and "awesome" and "simple", etc, etc, etc. Always reads like appeals to narcissism to me.
Is it really a big deal that people would like to just simply ID it as a grammar issue and basically is simply a useless phrase as it will be simple for some but not so much for others and let them judge how simple it is for themselves?
It signals the authors incompetency and is a red flag their code is a bug ridden hot mess caught up in ego stroking bullshit.
Simple, easy, lightweight - any project with that in the name is a sprawling trashpile.
Simple, easy, lightweight - any project with that in the name is a sprawling trashpile.
For those that don't find the irritation caused to others as a sufficient reason to stop doing it, consider that it just simply sounds unprofessional and basically just simply inhibits clarity. It sounds like a slightly more refined version of spamming, like, the filler word "like" all over your documentation.
People rightly deduct style and professionalism points for this regardless of whether they're personally offended.
People rightly deduct style and professionalism points for this regardless of whether they're personally offended.
> isn't that a clear hint that I'm still missing a concept somewhere and need to look around for an explanation?
No, it means you are being gaslit by an autistic nerd, there was no committee going over those docs it’s just one person’s interpretation and attempt at interacting with the rest of society
I agree with your general idea and great! Now we can just copy and paste the docs into chatgpt for a real explanation and move on
No, it means you are being gaslit by an autistic nerd, there was no committee going over those docs it’s just one person’s interpretation and attempt at interacting with the rest of society
I agree with your general idea and great! Now we can just copy and paste the docs into chatgpt for a real explanation and move on
The psychology involved in the response you're wondering about is really quite simple to understand.
Words have meaning.
And 92% of the time, "just" or "simply" have no useful meaning.
And 92% of the time, "just" or "simply" have no useful meaning.
shri_krishna(2)
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.
>> "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.
As a math professor, I had an epiphany about the word "easily" several years ago. In my course notes, I used that word to mean "I guarantee you don't need any additional ideas here, just do the obvious thing." Nothing more was meant.
But I realized that many students either didn't think the obvious thing was really that obvious, or maybe realized it but were reticent to follow that path because it invoved some tedious work and the prof said it was easy, so that couldn't be it.
Many students were also intimidated by that word, as if I were saying to them "if you don't find this easy, you shouldn't be here".
So I went on a deleting spree, removing most instances of "easy", "simple", and "just a matter of", and replacing them with a clearer explanation of what to do. My notes got better as a result. Less filler, less intimidation, more useful details.
But I realized that many students either didn't think the obvious thing was really that obvious, or maybe realized it but were reticent to follow that path because it invoved some tedious work and the prof said it was easy, so that couldn't be it.
Many students were also intimidated by that word, as if I were saying to them "if you don't find this easy, you shouldn't be here".
So I went on a deleting spree, removing most instances of "easy", "simple", and "just a matter of", and replacing them with a clearer explanation of what to do. My notes got better as a result. Less filler, less intimidation, more useful details.
And as a math student, I found myself using this as a strategy in reverse.
Finding myself in a tenuous part of a proof, I would say things like “clearly one can see that,” and jump a few steps. I think I was doing this to put the person looking at my work in the back foot, and it might’ve worked a couple of times!
Finding myself in a tenuous part of a proof, I would say things like “clearly one can see that,” and jump a few steps. I think I was doing this to put the person looking at my work in the back foot, and it might’ve worked a couple of times!
I suppose too that if something truly is easy or simple, it should be self-evident. What is the purpose of taking the time and energy to point out that something isn’t difficult? If it were true, a person would likely discover it themselves readily enough.
I find this kind of writing (and thinking in general) fairly commonplace. It’s a good exercise to take a step back and wonder: why did I write that? What did I actually mean by it? Is it necessary to state X or Y, or am I using it implicitly for some communicative purpose that should be explicit?
Stuff like this is why writing is actually quite hard, in my opinion.
I find this kind of writing (and thinking in general) fairly commonplace. It’s a good exercise to take a step back and wonder: why did I write that? What did I actually mean by it? Is it necessary to state X or Y, or am I using it implicitly for some communicative purpose that should be explicit?
Stuff like this is why writing is actually quite hard, in my opinion.
Whenever my professor said "it's easy to show" and then moved on it felt very hand wavy. The steps weren't obvious to me and didn't become more obvious as the course went on because no one taught me how to think of the "obvious" thing.
The worst situation in my college experience was when a prof would go over some mundane part of a proof in excruciating detail, and then hand-wave the important part. I realized later in life it was because they prof didn't understand it, either.
I had a similar situation after a "last chance" exam for one course.
The lecturer was unavailable, so he assigned a substitute to grade the exam. There was a problem there similar to the casting problem (assuming each subsequent candidate has probability P to be better than the previous one, when should we make our pick), only the probabilities were different each time - this wasn't covered in the course material. I deconstructed it by calculating all the probabilities by hand, because I didn't know any other way.
The substitute asked me to come by and explain how I solved it, because apparently I was the only one to do so.
The lecturer was unavailable, so he assigned a substitute to grade the exam. There was a problem there similar to the casting problem (assuming each subsequent candidate has probability P to be better than the previous one, when should we make our pick), only the probabilities were different each time - this wasn't covered in the course material. I deconstructed it by calculating all the probabilities by hand, because I didn't know any other way.
The substitute asked me to come by and explain how I solved it, because apparently I was the only one to do so.
Thank you! I think you correctly guessed what the students were thinking, because I have thought similar things.
One angle here is that academics are (rightly) proud of their specialist knowledge, and often using words like "simply" and "easily" really are a flex whether they know it or not. The best way as student can take this is as inspiration, that one day it will be easy for you, too. I personally believe empathy deserves high praise and recognition, a key part of pedagogy. However, the lack of empathy does not, in turn, deserve derision. Not everyone is a great, or even particularly good, teacher.
One angle here is that academics are (rightly) proud of their specialist knowledge, and often using words like "simply" and "easily" really are a flex whether they know it or not. The best way as student can take this is as inspiration, that one day it will be easy for you, too. I personally believe empathy deserves high praise and recognition, a key part of pedagogy. However, the lack of empathy does not, in turn, deserve derision. Not everyone is a great, or even particularly good, teacher.
I just want to say thank you for doing this. Please tell your community to do this too. I really struggled hearing such things in college.
It’s crazy to say, but I think not hearing what was “obvious” would have helped me excel more in my classes.
It’s crazy to say, but I think not hearing what was “obvious” would have helped me excel more in my classes.
Saying "easily" can be beneficial because it signals to the students "See? This is really not that bad."
Many students think their grade is worse than it actually is, they think they're worse at math than they actually are or they think the course is harder than it really is
Many students think their grade is worse than it actually is, they think they're worse at math than they actually are or they think the course is harder than it really is
I read something a while ago that resonated, and I tried it out and have had a lot of success with my kid.
If the kid is hesitant to try something that you know will end up being easy, the natural thing is to tell them it's going to be easy.
But if you tell someone something is easy, and their personal experience is already that it's hard, well, the conclusion isn't necessarily "oh I was wrong, now it's easy, thanks dad, I'll actually try now". It may instead be "oh wow I suck at the easy thing I guess".
So now I do the opposite. She's struggling with something? I tell her it's hard. And I pair it with some indication that it won't be hard forever and is worth learning.
So now if I see her struggling I don't say "This is easy, let me show you". I definitely don't say "This is easy, just give it a shot".
I say "Oh yeah, this part's hard at first. But I know a trick."
If the kid is hesitant to try something that you know will end up being easy, the natural thing is to tell them it's going to be easy.
But if you tell someone something is easy, and their personal experience is already that it's hard, well, the conclusion isn't necessarily "oh I was wrong, now it's easy, thanks dad, I'll actually try now". It may instead be "oh wow I suck at the easy thing I guess".
So now I do the opposite. She's struggling with something? I tell her it's hard. And I pair it with some indication that it won't be hard forever and is worth learning.
So now if I see her struggling I don't say "This is easy, let me show you". I definitely don't say "This is easy, just give it a shot".
I say "Oh yeah, this part's hard at first. But I know a trick."
It's a more and more popular opinion:
- Why not tell people to "simply" use pyenv, poetry or anaconda (https://bitecode.substack.com/p/why-not-tell-people-to-simpl...)
- Don’t use the word ‘simply’ (https://jameshfisher.com/2017/02/22/dont-use-simply/)
- Stop using ‘simply’ in tech instructions (https://www.parkersoftware.com/blog/stop-using-simply-in-tec...)
- Don’t say “simply” in your documentation (https://www.knowledgeowl.com/blog/posts/dont-say-simply-jim-...)
And I strongly agree. It can be so discouraging to fail at something you should "simply" do.
But to be fair to the technical writers, it's easy to write that way without noticing, even after proof reading. This should be automatized by writing tools.
Also, while it's mildly irritating, there are worse things in life.
Yet as the first link about the python ecosystems notes, it usually hides a bigger problem: many devs are too good to be helpful.
- Why not tell people to "simply" use pyenv, poetry or anaconda (https://bitecode.substack.com/p/why-not-tell-people-to-simpl...)
- Don’t use the word ‘simply’ (https://jameshfisher.com/2017/02/22/dont-use-simply/)
- Stop using ‘simply’ in tech instructions (https://www.parkersoftware.com/blog/stop-using-simply-in-tec...)
- Don’t say “simply” in your documentation (https://www.knowledgeowl.com/blog/posts/dont-say-simply-jim-...)
And I strongly agree. It can be so discouraging to fail at something you should "simply" do.
But to be fair to the technical writers, it's easy to write that way without noticing, even after proof reading. This should be automatized by writing tools.
Also, while it's mildly irritating, there are worse things in life.
Yet as the first link about the python ecosystems notes, it usually hides a bigger problem: many devs are too good to be helpful.
Similarly, one should never state that something is "obvious".
I catch myself sometimes starting a sentence with "Obviously," and usually stop myself at that point and restart.
I catch myself sometimes starting a sentence with "Obviously," and usually stop myself at that point and restart.
True, there is no such thing as a concept been obvious to everybody.
Feyman has this great bit in his biography where he tackles mathematicians that keep saying in their demonstration that a step is trivial.
Feyman has this great bit in his biography where he tackles mathematicians that keep saying in their demonstration that a step is trivial.
Clearly, there are other words which sound condescending.
Reading text (documentation, for example) is more enjoyable when it inspires one's curiosity instead of belittling them on things which are simple, easy, obvious, clear, etc. Although humor helps, makes it stick.
Reading text (documentation, for example) is more enjoyable when it inspires one's curiosity instead of belittling them on things which are simple, easy, obvious, clear, etc. Although humor helps, makes it stick.
> Clearly, there are other words which sound condescending.
Well played. You start with a synonym for obviously, but pointing that out just proves your point.
Maybe there are some sentences that can justifiably start with obviously, clearly, etc after all
Well played. You start with a synonym for obviously, but pointing that out just proves your point.
Maybe there are some sentences that can justifiably start with obviously, clearly, etc after all
At first I agreed with you in that my spouse had a negative response to me referring to a particular person, method, place or thing as “famous” when she was not aware of the person. I’ve learned to omit it or say “well known in some circles” or the like.
On the other hand, maybe these phrases like “simply” or “obviously”are less-than-consciously used on the part of the speaker/writer to acknowledge that this reference may already be known to the listener/reader. In that it reminds me of various England-Englishisms that mean the opposite of their plain definitions.
On the other hand, maybe these phrases like “simply” or “obviously”are less-than-consciously used on the part of the speaker/writer to acknowledge that this reference may already be known to the listener/reader. In that it reminds me of various England-Englishisms that mean the opposite of their plain definitions.
> Similarly, one should never state that something is "obvious".
Agreed.
Logically speaking, if something is obvious, why are you wasting time stating it?
Either you've wasted everyone's time or it wasn't obvious.
Agreed.
Logically speaking, if something is obvious, why are you wasting time stating it?
Either you've wasted everyone's time or it wasn't obvious.
I often reply back quietly or in my head "obviously" with a bit of a laugh when I hear it used. It usually sounds absurd and unnecessary and takes me out of what was being said.
"Obviously" will always remind me of math classes in university. Sometimes the professor would use it as a joke, sometimes they used it normally while still stumping everyone else.
"Simply" when used in the sense of "without addition, alone" is perfectly fine. I find the issue people have is not really with the word simply but with bad documentation and badly designed tools. That’s not going to be fixed by avoiding one word.
“Simple” vs “easy”: https://youtu.be/LKtk3HCgTa8
Ok, so at least I‘m not the only one using simply that way
I remember reading one of those and it made a huge impression on me. I've followed it ever since and taught others to do the same. As far as I can tell, it has only been met with appreciation.
That said, sometimes I find myself trying to write around "simple" when I really mean "less complex", and I have to remind myself that what I really want to avoid is implying "easy", not "relatively less complex".
That said, sometimes I find myself trying to write around "simple" when I really mean "less complex", and I have to remind myself that what I really want to avoid is implying "easy", not "relatively less complex".
Indeed. I tend to force myself to write the following:
- It will be easy => I will guide you through it
- This will make your life easy => It will make your life easier / It will help you
- To do X, simply do Y => The most common way to get to X is first to do Y
- It will be easy => I will guide you through it
- This will make your life easy => It will make your life easier / It will help you
- To do X, simply do Y => The most common way to get to X is first to do Y
You can use comparatives, like "simpler", usually without issues. Something can be simpler than something else without necessarily being simple. Superlatives like "simplest" can sometimes be used as well. After all, being the simplest thing means to be simpler than all the other things; still not necessarily simple.
It's only the positive form "simple" which is problematic and should be almost always avoided.
It's only the positive form "simple" which is problematic and should be almost always avoided.
This is indeed where I usually go. "Under condition X, it is simpler to Y" rather than "Under condition X, you can simply Y."
it's not only the word `simply`; I find myself perusing more and more docs that boil down to an emoji-laden slab of super-shallow tutorials and marketing lingo, which just tell you how to do the most basic thing - or the barely less basic thing in the most ideal scenario - and nothing more.
I'm all ok with tutorials and examples into the docs, but give some depth to them, not only breadth (or emojis).
I'm all ok with tutorials and examples into the docs, but give some depth to them, not only breadth (or emojis).
> This should be automatized by writing tools.
iA Writer¹ does it. It strikes out and greys out the words “simply” and “just” as part of its style check for fillers.
¹ https://ia.net/writer
iA Writer¹ does it. It strikes out and greys out the words “simply” and “just” as part of its style check for fillers.
¹ https://ia.net/writer
The intro video for that app is one of the best I’ve seen in explaining quickly the value proposition of the software.
Many websites for software use so many buzzwords or marketing language as to not effectively communicate the value of the software.
Many websites for software use so many buzzwords or marketing language as to not effectively communicate the value of the software.
In the case of documentation provided by the creators of the software, there's a more substantial vexation:
Use of such words comes off as vacuous, self-praising bullshit.
Monty Python’s sketch “How to Do It” has some decades.
Regarding docs: Most recent projects that i looked into and tried evaluating are very focused on the shiny parts and all the nice features it got and bells and whistles.... it sometimes reads like an ad or an sales pitch.
But, I'm a sysadmin. I will be carrying operational responsibility for that thing if we decide to adopt it. I'd love to know what are the most common modes for it to break, what the cuts are where you could swap in your code, resource usage, update cycles and stability guarantees of these updates. Existence of a downgrade path (looking at you, kubernetes!). Ideally you'd know ahead if you are getting something robust where you can safely take a week off without any risks or something that needs to keep a firefighting team on-call for the rest of its lifetime.
I think a lot more needs to be done on the docs than omitting some words...
But, I'm a sysadmin. I will be carrying operational responsibility for that thing if we decide to adopt it. I'd love to know what are the most common modes for it to break, what the cuts are where you could swap in your code, resource usage, update cycles and stability guarantees of these updates. Existence of a downgrade path (looking at you, kubernetes!). Ideally you'd know ahead if you are getting something robust where you can safely take a week off without any risks or something that needs to keep a firefighting team on-call for the rest of its lifetime.
I think a lot more needs to be done on the docs than omitting some words...
Not to jump on GPT hype too much, but a good idea perhaps for an addon targeting OSS, read over issues, PRs, scrub Stack Overflow and compile a descriptive list of the most common pitfalls for a certain lib.
It's exactly the type of writing OSS authors don't like doing, and all the information is publicly available.
It's exactly the type of writing OSS authors don't like doing, and all the information is publicly available.
The problem is a lot of it is not publicly available. E.G: I asked chat gpt to help me install Python on Ubuntu 22.04, and it failed miserably.
Why? Because 22.04 is recent and many pitfalls it comes with haven't been much documented yet.
And it also don't know what is never written, but implicitly known if you deal with a lot of beginners. E.G: people get utterly confused with *args and **kwargs in Python, because it can be used at 2 different places, and depending of those places, it does completely different things. The latter is well documented, but that the brain of people cannot grok it is not.
So chatgpt will explain the same things as most of the doc, without realizing that what it needs to do is to warn humans that they are going to be confused and how to avoid it.
Humanity has a lot of implicit knowledge.*
Why? Because 22.04 is recent and many pitfalls it comes with haven't been much documented yet.
And it also don't know what is never written, but implicitly known if you deal with a lot of beginners. E.G: people get utterly confused with *args and **kwargs in Python, because it can be used at 2 different places, and depending of those places, it does completely different things. The latter is well documented, but that the brain of people cannot grok it is not.
So chatgpt will explain the same things as most of the doc, without realizing that what it needs to do is to warn humans that they are going to be confused and how to avoid it.
Humanity has a lot of implicit knowledge.*
There's an explicit caveat on chat gpt: limited knowledge of the world and events after 2021. You're asking about 22.04.
GPT != Chat GPT, GPT-4, etc.
It’s possibly to [“just simply”] train a GPT on whatever corpus you want.
It’s possibly to [“just simply”] train a GPT on whatever corpus you want.
For reference this is what I meant, either use some GPT-like LLM or pass on a large prompt of data previously scrapped into OpenAI GPT-4 as it currently accepts ~8k words for input in the paid plan.
You can train GPT 2 on whatever you want, it will give you the wrong answer for everything.
The real magic arrived with GPT3, which is proprietary, so it's fair to assume your audience understands this and imply it.
The real magic arrived with GPT3, which is proprietary, so it's fair to assume your audience understands this and imply it.
GPT-3 is opensource. GPT-4 isn't.
https://github.com/openai/gpt-3
https://github.com/openai/gpt-3
I get this a lot while reading about something new which I have heard might solve my problem, or while better trying to understand a system already in place. The documentation begins with a comforting high level description that is vague enough to sound like it might fit my use case, but then abruptly transitions into a table of contents listing the minutiae of interfaces, API calls, system components, without giving a suitable intermediary description of how any of these things might work in concert to actually solve the problem. This is left as an exercise to the reader.
You will almost never be offered any central insight from the author(s) about their mental framework for the system they have designed, or even that of the problem that it is intended to solve (so that you might more quickly determine whether your particular problem is a member of this class). Instead, I will often find this missing information presented in a random blog of some individual who, having won this knowledge through heroic effort, is determined to provide the context that they would have wished to find themselves upon first starting their journey.
Why does it have to be this difficult?
I suspect a lot of this has to do with the organization of companies involved (Google and Microsoft are some of the worst offenders here) in that the people writing the documentation are often not the people creating the systems, and so don't really understanding anything they are describing themselves. Meanwhile, those that designed the system suffer from the Curse of Expertise where their familiarity blinds them to things that are "obvious" to them, but are not actually inherent to the system they have designed. They are ignorant of all of the background understanding and experience that lead them to design the system or approach the problem in a particular way, when this is actually the most valuable thing I look for in any documentation I read.
You will almost never be offered any central insight from the author(s) about their mental framework for the system they have designed, or even that of the problem that it is intended to solve (so that you might more quickly determine whether your particular problem is a member of this class). Instead, I will often find this missing information presented in a random blog of some individual who, having won this knowledge through heroic effort, is determined to provide the context that they would have wished to find themselves upon first starting their journey.
Why does it have to be this difficult?
I suspect a lot of this has to do with the organization of companies involved (Google and Microsoft are some of the worst offenders here) in that the people writing the documentation are often not the people creating the systems, and so don't really understanding anything they are describing themselves. Meanwhile, those that designed the system suffer from the Curse of Expertise where their familiarity blinds them to things that are "obvious" to them, but are not actually inherent to the system they have designed. They are ignorant of all of the background understanding and experience that lead them to design the system or approach the problem in a particular way, when this is actually the most valuable thing I look for in any documentation I read.
I’ve seen worse.
— an emoji-laden intro employing borderline UwU-speak
— jumping into API reference immediately after
— the reference is auto-generated with half of it being stubs, implying you should throw it away and just simply read the code
— an emoji-laden intro employing borderline UwU-speak
— jumping into API reference immediately after
— the reference is auto-generated with half of it being stubs, implying you should throw it away and just simply read the code
I'm surprised nobody has pointed out yet that "Mailers are another way to render a view" has lost information that was present in "Mailers are really just another way to render a view.".
The author of this post appears to want to adopt the most infuriating traits of the MSDN documentation: namely, converting all documentation into a list of facts ("Mailers are another way to render a view", "a common use of mailers is…"). This is bad because if you are presented with a bare list of facts, you can't judge their relative importance, or how they relate to each other. The original Rails example was bad, but rather than fix it, they have rewritten it to make the badness more obvious.
The original was bad not because it uses the words "just" and "simply", but because it's verbose while still being hard to read. I still don't understand what the sentence starting "Due to this" is trying to say, and it's very unclear where they transition from giving general technical facts to walking through the specifics of the example. (It is certainly wrong to call something "painfully simple" - I can imagine maybe one or two places where it's ever appropriate - but it's not the main thing that is wrong with those docs.)
But the first two sentences of the original docs were easier to understand than the rewritten version. Compare:
> Mailers are really just another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they are just sending it out through the email protocols instead.
> Mailers are another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they send it out through email protocols instead.
I mean, is it rendering a view or isn't it?! The second version explicitly contradicts itself much more baldly than the first version, where the words "just" performed an important function by indicating that the sentence is about what is different between mailers and other renderers.
In the rewritten version, two of the three sentences of the first paragraph explicitly contradict each other, and the third is totally unrelated to what came before. This was a structural deficiency of the original docs, but removing the narrative elements of the text has amplified the problem to the point of absurdity.
The author of this post appears to want to adopt the most infuriating traits of the MSDN documentation: namely, converting all documentation into a list of facts ("Mailers are another way to render a view", "a common use of mailers is…"). This is bad because if you are presented with a bare list of facts, you can't judge their relative importance, or how they relate to each other. The original Rails example was bad, but rather than fix it, they have rewritten it to make the badness more obvious.
The original was bad not because it uses the words "just" and "simply", but because it's verbose while still being hard to read. I still don't understand what the sentence starting "Due to this" is trying to say, and it's very unclear where they transition from giving general technical facts to walking through the specifics of the example. (It is certainly wrong to call something "painfully simple" - I can imagine maybe one or two places where it's ever appropriate - but it's not the main thing that is wrong with those docs.)
But the first two sentences of the original docs were easier to understand than the rewritten version. Compare:
> Mailers are really just another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they are just sending it out through the email protocols instead.
> Mailers are another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they send it out through email protocols instead.
I mean, is it rendering a view or isn't it?! The second version explicitly contradicts itself much more baldly than the first version, where the words "just" performed an important function by indicating that the sentence is about what is different between mailers and other renderers.
In the rewritten version, two of the three sentences of the first paragraph explicitly contradict each other, and the third is totally unrelated to what came before. This was a structural deficiency of the original docs, but removing the narrative elements of the text has amplified the problem to the point of absurdity.
Both versions are bad, because in both cases the first sentence says that mailers are "another way to render a view", while the second sentence says they are another way to "send" an already-rendered view.
> I mean, is it rendering a view or isn't it?!
It is rendering a view, and both versions make that clear. There's no contradiction in the rewritten version.
> I mean, is it rendering a view or isn't it?!
It is rendering a view, and both versions make that clear. There's no contradiction in the rewritten version.
One of the best pieces of advice I learned in high school from an incredible English teacher: when doing technical, avoid "-ly" words entirely. It has always been solid advice and has rarely led me astray.
> when doing technical, avoid "-ly" words entirely.
Following its own advice, “entirely” can be cut without loss of meaning. Considering the replies you’re getting, perhaps a better way to phrase it in the future would be:
> eschew "-ly" adverbs.
That way it’s clear you’re referring to a specific subset of adverbs.
Following its own advice, “entirely” can be cut without loss of meaning. Considering the replies you’re getting, perhaps a better way to phrase it in the future would be:
> eschew "-ly" adverbs.
That way it’s clear you’re referring to a specific subset of adverbs.
> avoid "-ly" words
I hope this isn’t the actual advice you were given. They are called adverbs.
I hope this isn’t the actual advice you were given. They are called adverbs.
It was the exact advice given. Not all adverbs end in "-ly", either, and not all adverbs should be avoided in technical writing; that'd be impossible.
The rule states "-ly" words because those words are often cruft or crutch words that can be removed. If the sentence can't stand on its own without that word, then the sentence probably doesn't belong in the body of technical writing.
Compare this with time-related adverbs, which generally provide chronological structure. Those are more relevant for technical writing.
So yes, avoid "-ly" words. Not adverbs in general. That was the advice given.
The rule states "-ly" words because those words are often cruft or crutch words that can be removed. If the sentence can't stand on its own without that word, then the sentence probably doesn't belong in the body of technical writing.
Compare this with time-related adverbs, which generally provide chronological structure. Those are more relevant for technical writing.
So yes, avoid "-ly" words. Not adverbs in general. That was the advice given.
Some adverbs not ending in "-ly" are always, soon, today, ever, yet.
"The Python interpreter has a number of functions and types built into it that are always available." [1]
"Long option values can be split across multiple lines simply by indenting the continuation lines." [2]
Agree with your teacher in that the first one seems fine. [1] https://docs.python.org/3/library/functions.html
[2] https://docs.python.org/3/distutils/configfile.html
"The Python interpreter has a number of functions and types built into it that are always available." [1]
"Long option values can be split across multiple lines simply by indenting the continuation lines." [2]
Agree with your teacher in that the first one seems fine. [1] https://docs.python.org/3/library/functions.html
[2] https://docs.python.org/3/distutils/configfile.html
I think that the advice is a bit more nuanced, your first example is fine as it is but consider the variants:
"...that are clearly always available."
"...that are obviously available."
"...that are simply available."
These adverbs are not only redundant but their presence suggest that things are actually not clear, simple or obvious.
"...that are clearly always available."
"...that are obviously available."
"...that are simply available."
These adverbs are not only redundant but their presence suggest that things are actually not clear, simple or obvious.
For non-native English speakers -ly is simpler than adverts. But simpler does not necessarily mean better long-term.
Why is it simpler? Are non-native English speakers less likely to know what an adverb is than English speakers are? I doubt it.
In their own language they know it but uncommon words in a non-native language might have to be looked up. Its theoretical vs practical.
I am a non-native English speaker, fwiw.
This is a rule in the Hemingway app: https://hemingwayapp.com/
[deleted]
What, like "butterfly"?
Avoiding "butterfly" when writing technical documentation sounds like a good advice.
The keyboard in your thinkpad 701C has a mechanism we affectionately call butter… oh never mind.
"Affectionately"?! One point for Slytherin!
C-h f butterflyLike "otherwordly", obviously.
Never use "otherwordly" ph'nglui technical documentation, ngnah ymg' risk s̵͖͕͓̒̾̾ǘ̵̢̺͓͊́m̵̟͙̓̒̚m̴͉̠͖̈́͊͠o̸̞̺̻̾́̀n̵͖̻͓̓̔i̴̢͚͕̿̕͝n̴͇̞͎͒̀̚g̵̢̟͙̾̚͝ z̴̪̠̟̾̿͘a̸͇̞͙̔͌͛l̵̢̟̘͆̒g̴͓͔̀́̿ö̵̪̠́͑̓.̴̢͙̪́͝͠
Never use "otherwordly" ph'nglui technical documentation, ngnah ymg' risk s̵͖͕͓̒̾̾ǘ̵̢̺͓͊́m̵̟͙̓̒̚m̴͉̠͖̈́͊͠o̸̞̺̻̾́̀n̵͖̻͓̓̔i̴̢͚͕̿̕͝n̴͇̞͎͒̀̚g̵̢̟͙̾̚͝ z̴̪̠̟̾̿͘a̸͇̞͙̔͌͛l̵̢̟̘͆̒g̴͓͔̀́̿ö̵̪̠́͑̓.̴̢͙̪́͝͠
My stance is really not in favor or against using (or overusing) a word from a "blacklisted" set, it's more that usually the structure doesn't cater well to the audience and on top of that it adds a lot of unnecessary fluff. If I need to download X dependencies but two of them need to be version 1.2.3, by all means tell me it's all super simple to do, idc, really. But give me the exact dependencies that NEED that version for the thing to work. Worse than this unnecessary fluff and eagerness for simplicity or wtv is having incomplete instructions that lead to a non-working setup by the end. Proofread them by EXECUTING them and then, as long as it works, be a Shakespeare about it. There seems to be a lot the expectations of things being broken and a kind of tragedy of the commons being the standard.
It bothers me when someone good/bad naturedly corrects me on "blacklist" and encourages me to say "blocklist". I figure that stems from either overactive empathy or is a power play. Please continue to say "blacklist".
I see “blocklist” becoming more popular in programming. But it just occurred to me how bizarre and out of place it would be if the parent comment said “a blocklisted word”.
Plenty of people now say allowlist and denylist instead of whitelist and blacklist.
Goodlist and ungoodlist.
Blocklist for me is a list of blocks, like the one you gather with badblocks(8) and then pass to fsck(8).
I wish people would stop conflating "simple" and "easy".
Git's core internals are simple but using it is not easy. Simple things can have very complex implications. If an API is too simple, you have to build complex things on top to make it work for you.
Python is easy for beginners but it isn't a simple language. In fact, it belongs to the more complicated ones. Making something easy usually requires a lot work.
Git's core internals are simple but using it is not easy. Simple things can have very complex implications. If an API is too simple, you have to build complex things on top to make it work for you.
Python is easy for beginners but it isn't a simple language. In fact, it belongs to the more complicated ones. Making something easy usually requires a lot work.
Germans here?
If you need instructions it is NOT simple for your users.
The word doesn’t add info. The text to comprehend becomes longer. And the task even harder for readers. I started using “einfach” too much and now delete it whenever appropriate.
Klicken sie einfach auf “Ausführen”.
Click simply on “Execute”.
If you need instructions it is NOT simple for your users.
The word doesn’t add info. The text to comprehend becomes longer. And the task even harder for readers. I started using “einfach” too much and now delete it whenever appropriate.
I mean sometimes things are simple, and are put in docs because someone doesn't get what's obvious, I had to sometimes to shut myself from offending people who were stuck on screens that were so obvious and instead of trying and fail or google, waited for the help of someone to unstuck them, docs exist with simple things inside and that is not enough to measure if those things are simple or not, they also exist like if that one guy who couldn't understand the obvious and had to ask, does a doc that documents something that was understood without it by 999 people, make what is documented unclear because of 1 that couldn't see?
if you go to a place where you see a sign "Don't touch the fire", does it make not touching the fire not obvious because the sign exist? Or we have to put obvious sign for those who aren't cerebrally developed enough to understand it without the sign?
if you go to a place where you see a sign "Don't touch the fire", does it make not touching the fire not obvious because the sign exist? Or we have to put obvious sign for those who aren't cerebrally developed enough to understand it without the sign?
Wording is one thing, but what is always annoying moving to a new library or language is the tacit knowledge the docs assume.
It's a fine line, one can assumes a certain knowledge to even be functional, but in doubt I think it's better to be extra verbose.
Few examples: - JS libraries not showing how to import the modules used in code examples. - Everything in the kubernetes docs - In Xcode explanations often it just mentioned: go the "build settings", etc. In beginning it's extremely confusing to find anything in that program.
It's a fine line, one can assumes a certain knowledge to even be functional, but in doubt I think it's better to be extra verbose.
Few examples: - JS libraries not showing how to import the modules used in code examples. - Everything in the kubernetes docs - In Xcode explanations often it just mentioned: go the "build settings", etc. In beginning it's extremely confusing to find anything in that program.
I disagree with this pretty vehemently. There is value in a doc telling you “this sounds like a complicated concept, but it’s actually not”. As a reader, it can tell you that you don’t need to dig for deeper meaning or start searching for and understanding all the related concepts.
This particularly comes up when a concept has an unfamiliar name because of how it fits in with things conceptually, but at its core it’s just a very familiar entity with some other familiar entity tacked on, or something like that.
For an example off the top of my head: “A tagged image is simply a JSON object with an ‘image’ data URI property, and a ‘metadata’ object property”. The word “simply” is pulling weight here. It’s telling the reader that there is nothing else to the concept, that they already understand everything there is to know, and they can move on.
This can be misused, of course, and I think the post’s example is a valid one. But it’s a lot more useful to say when you should use something in your writing than it is to say “you probably shouldn’t.”
This particularly comes up when a concept has an unfamiliar name because of how it fits in with things conceptually, but at its core it’s just a very familiar entity with some other familiar entity tacked on, or something like that.
For an example off the top of my head: “A tagged image is simply a JSON object with an ‘image’ data URI property, and a ‘metadata’ object property”. The word “simply” is pulling weight here. It’s telling the reader that there is nothing else to the concept, that they already understand everything there is to know, and they can move on.
This can be misused, of course, and I think the post’s example is a valid one. But it’s a lot more useful to say when you should use something in your writing than it is to say “you probably shouldn’t.”
I agree with the post. If you consider that your docs are also a form of advertising... don't shoot yourself in the foot and make your readers feel stupid.
I would go one step further. If we are talking about CLI tool usage - the cli should have two modes. One interactive using gum or some similar library. Once complete - it should output the non-interactive equivalent CLI command.
The interactive run should give short explanations to help learn the tool.
The takeaway point is that docs are partially advertisements - and if you don't want to lose people - your docs have to be carefully crafted.
I would go one step further. If we are talking about CLI tool usage - the cli should have two modes. One interactive using gum or some similar library. Once complete - it should output the non-interactive equivalent CLI command.
The interactive run should give short explanations to help learn the tool.
The takeaway point is that docs are partially advertisements - and if you don't want to lose people - your docs have to be carefully crafted.
I understand the author’s point yet think it’s OK.
Why? Because when I encounter “simple” in that context I read “If you understand the domain this package allows you to perform calculations (or whatever) and will operate in a way you will expect”.
Some examples: IEEE floating point is a simple FP standard, even though the document is really long and full of non-obvious cases and a couple of footguns for the naive. It’s simple for someone doing serious numerics (and even simple for a most common cases with a little training) because someone put the hard work in, so the user doesn’t have to code up allot of infrastructure.
MS word makes it easy for someone like me to change font sizes, center some text etc, but a sophisticated designer probably fights Word’s DWIM and would prefer a more sophisticated tool with more knobs, because that would be simpler for hem to use.
And so on.
Why? Because when I encounter “simple” in that context I read “If you understand the domain this package allows you to perform calculations (or whatever) and will operate in a way you will expect”.
Some examples: IEEE floating point is a simple FP standard, even though the document is really long and full of non-obvious cases and a couple of footguns for the naive. It’s simple for someone doing serious numerics (and even simple for a most common cases with a little training) because someone put the hard work in, so the user doesn’t have to code up allot of infrastructure.
MS word makes it easy for someone like me to change font sizes, center some text etc, but a sophisticated designer probably fights Word’s DWIM and would prefer a more sophisticated tool with more knobs, because that would be simpler for hem to use.
And so on.
While we're here, could we also please have clear separation between commands and data? Eg, I hate stuff like:
$ bin/rails generate scaffold user name email login
$ bin/rails --generate=scaffold --user=name --email=login
$ bin/rails --generate=scaffold --user=username --name=fullname --email=address --login=login_name
$ bin/rails --generate --scaffold=user --name=fullname --email=address --login=login_name
The long-standing convention here, particularly for command line usage, is that:
- String literals should be in lowercase (because by convention commands, argument names, etc should always be in all-lowercase, eg. "git cherry-pick" not "git cherryPick" or "git CHERRY-PICK")
- Metavariables (stuff the user should fill in) should be in ALL-CAPS.
- Not as strictly adhered to but still useful, [optional part] and {repeatable part}.
So eg. your example might look like:
- String literals should be in lowercase (because by convention commands, argument names, etc should always be in all-lowercase, eg. "git cherry-pick" not "git cherryPick" or "git CHERRY-PICK")
- Metavariables (stuff the user should fill in) should be in ALL-CAPS.
- Not as strictly adhered to but still useful, [optional part] and {repeatable part}.
So eg. your example might look like:
$ bin/rails generate scaffold --user=NAME --email=LOGIN
$ bin/rails generate scaffold --user=ekimekim [email protected]
> Metavariables (stuff the user should fill in) should be in ALL-CAPS.
If possible, (like it is here on HN), metavariables should be in ALL_CAPS_AND_ITALICS, because that’s how it’s done in Unix manual pages.
If italics is not available, it might be more clear to use the $SHELL_VARIABLE convention, depending on the audience.
If possible, (like it is here on HN), metavariables should be in ALL_CAPS_AND_ITALICS, because that’s how it’s done in Unix manual pages.
If italics is not available, it might be more clear to use the $SHELL_VARIABLE convention, depending on the audience.
In your example you're using rails but isn't this a problem with every command line tool ever that has positional arguments?
cp a b
rm -f a b c
etc.
Especially when we have the entirety of modern monitors available to us, use color to indicate which parts of the command/code are mandatory/boilerplate and which are optional, and which are the actual "values" you'll be using.
Color might not be available, like here in HN comments.
In older texts, the <angle-brackets> convention was common, but became less so probably due the emergence of HTML. Nowadays, I most commonly see the $SHELL_VARIABLE convention. Man pages use UPPERCASE_ITALICS (or uppercase underlined on terminals).
In older texts, the <angle-brackets> convention was common, but became less so probably due the emergence of HTML. Nowadays, I most commonly see the $SHELL_VARIABLE convention. Man pages use UPPERCASE_ITALICS (or uppercase underlined on terminals).
I'd say it's the last one, with a "subcommand based position dependant syntax" like git or zfs. It's a matter of taste but personally I prefer it to the traditional one. As long as the behavior is consistent remembering the order of the arguments is often easier than remembering the exact keywords.
Its trivial. The obvious solution is to just simply read the extremely friendly documentation. /s
Good discussion in 2021 (249 points, 138 comments):
https://news.ycombinator.com/item?id=27418577
https://news.ycombinator.com/item?id=27418577
I agree with the article, but to be fair, all software aims to simplify a task. So calling a procedure "simple" is usually done in comparison with what used to be more difficult/complicated.
Though my biggest annoyance with this is when it's part of network protocol names: SNMP, SMTP, TFTP, etc. What you usually find when working with these is that they're far from being simple, so it borders on false advertising. Maybe they start that way, and that is the author's vision, but when they mature it often stops being true. Or maybe they were simple compared to what predated them, and for their time and place. But it's still a bad idea to name a protocol or standard that.
Though my biggest annoyance with this is when it's part of network protocol names: SNMP, SMTP, TFTP, etc. What you usually find when working with these is that they're far from being simple, so it borders on false advertising. Maybe they start that way, and that is the author's vision, but when they mature it often stops being true. Or maybe they were simple compared to what predated them, and for their time and place. But it's still a bad idea to name a protocol or standard that.
> I agree with the article, but to be fair, all software aims to simplify a task. So calling a procedure "simple" is usually done in comparison with what used to be more difficult/complicated.
It follows that calling anything "simple" is redundant. Either it's implied (i.e. "of course it should be simple, otherwise I'd just use X"), or it's wrong. Indicating the difficulty of anything has no place in any technical text.
It follows that calling anything "simple" is redundant. Either it's implied (i.e. "of course it should be simple, otherwise I'd just use X"), or it's wrong. Indicating the difficulty of anything has no place in any technical text.
So, it's off limits in a technical text to say that, say !(!a && !b) simplifies to a || b, or anything else in a similar vein?
In English, the math jargon term “simplifies to” means roughly “is equivalent to this less complex form”. It does not connote difficulty.
It absolutely denotes difficulty. E.g. more machine cycles are needed to traverse the original expression tree that has more nodes.
You dropped the context of the discussion. We aren’t talking about machines, but humans.
That is a different usage of the word “difficulty”, meaning something requiring more work to achieve an outcome, but that is not the relevant meaning in this context.
In the context of this discussion, “difficulty” is being used to describe the level of significant and sustained focused mental effort to grasp and integrate a new concept into one’s existing body of knowledge.
That is a different usage of the word “difficulty”, meaning something requiring more work to achieve an outcome, but that is not the relevant meaning in this context.
In the context of this discussion, “difficulty” is being used to describe the level of significant and sustained focused mental effort to grasp and integrate a new concept into one’s existing body of knowledge.
Super frustrating.
There’s a lot of “just do x” in stack overflow answers as well.
It “just” makes the reader feel stupid.
There’s a lot of “just do x” in stack overflow answers as well.
It “just” makes the reader feel stupid.
Big agree, everytime I find myself typing a comment on slack along the lines of "can we just do x", I immediately stop and delete the word just. The message doesn't loose any meaning and is a lot less obnoxious.
I like that the example is talking exactly about Rails Mailer. I've used it once and it was really painful to setup, which is exactly the post point. Love it.
This is absolutely true. It irritates me to no end when I read something that goes "oh, flooricating is so easy, you just scombobulate the foolarizer with bardotic parameters like this: <magic incantation>". No, dude, it's not easy: if it were, we wouldn't be here - most people don't like to read manuals or even ask for help, if they can avoid it.
Something that I always keep in mind is the rather complete and thoughtful GitLab Documentation Style Guide [1].
1. https://docs.gitlab.com/ee/development/documentation/stylegu...
1. https://docs.gitlab.com/ee/development/documentation/stylegu...
> Write in US English with US grammar. (Tested in British.yml.)
heh, that was funny but it turns out the file is a list of British words checked using Vale, which I just learned existed: https://github.com/errata-ai/vale#readme (MIT)
Also, another TIL is that the "e" version of gray is British https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale... I had previously erroneously assumed they were just one of those quirks of English (which, I guess is still true but it is less random than I thought)
heh, that was funny but it turns out the file is a list of British words checked using Vale, which I just learned existed: https://github.com/errata-ai/vale#readme (MIT)
Also, another TIL is that the "e" version of gray is British https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale... I had previously erroneously assumed they were just one of those quirks of English (which, I guess is still true but it is less random than I thought)
Simplicity is asserted as much as it is true. Such that, you will be surprised how effective saying something is simple is at getting uptick in it. My goto evidence for this, for a while, has been Python. It is no "simpler" than pretty much any other option nowadays. What it has going for it is an audience that as bought in to how simple it is. And they evangelize it. With those terms. Heavily.
Is it somewhat obnoxious? I mean, yeah. I'm very sympathetic to the idea. At old job, we would harp on "weasel words" that were there and served no purpose. But, there is a catch, they absolutely work on audiences that are not primed against them. Can they be overdone? Absolutely, but there are solid reasons you will see them over and over.
Is it somewhat obnoxious? I mean, yeah. I'm very sympathetic to the idea. At old job, we would harp on "weasel words" that were there and served no purpose. But, there is a catch, they absolutely work on audiences that are not primed against them. Can they be overdone? Absolutely, but there are solid reasons you will see them over and over.
I don't entirely disagree with the sentiment, but the example is so contrived. The problem with these sentences isn't that the word "just" and "simply" are somehow upsetting to the reader but that they're clumsy sentences.
"Mailers are really just another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they are just sending it out through the email protocols instead. Due to this, it makes sense to just have your controller tell the Mailer to send an email when a user is successfully created.
Setting this up is painfully simple."
That said, I think there's rarely a good reason to say something is "simple" in documentation. Explain how to do it and let the user decide if it's simple.
"Mailers are really just another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they are just sending it out through the email protocols instead. Due to this, it makes sense to just have your controller tell the Mailer to send an email when a user is successfully created.
Setting this up is painfully simple."
That said, I think there's rarely a good reason to say something is "simple" in documentation. Explain how to do it and let the user decide if it's simple.
It wasn't an example: it was copied and pasted from the Rails guides at the time.
Oh wow, okay. That sounded so bad I didn't think it could possibly be from the real documentation for a pretty popular product.
I know: bonkers!
The problem with using "simple" is that it's ambiguous. Are you talking about the opposite of sophisticated? the opposite of difficult? the opposite of complex? It has virtually no meaning without context.
So if you're tempted to write simple, remove it and say exactly what you mean.
Often times, documentation writers say "simply do X" when they mean "as a prerequisite, this document assumes the reader has an understanding of Y such that they can accomplish X without any further instructions". There's nothing wrong with having prerequisites; you have to assume the reader has some knowledge upon which to build. Make that explicit rather than hidden behind a "simply".
So if you're tempted to write simple, remove it and say exactly what you mean.
Often times, documentation writers say "simply do X" when they mean "as a prerequisite, this document assumes the reader has an understanding of Y such that they can accomplish X without any further instructions". There's nothing wrong with having prerequisites; you have to assume the reader has some knowledge upon which to build. Make that explicit rather than hidden behind a "simply".
I have embraced the idea that nobody wants to read what I write.
I think that everyone is going to close my document at any moment, so I communicate as clearly as possible.
My tech writing reads like it’s for kids, but coworkers seem to like it.
I think that everyone is going to close my document at any moment, so I communicate as clearly as possible.
My tech writing reads like it’s for kids, but coworkers seem to like it.
Personally I prefer that type of sentences, it allows me to know which procedures are easy once you know them, and which aren't.
If you are new, everything is difficult. But if you read that something is simple you know that, even though for you right now it isn't, it will be in the future.
If you have issues with that simple task, maybe you are doing it wrong and should ask for help. On the other hand, if the documentation says that something is hard, you shouldn't even attempt it as a beginner, and perhaps wait until you have more experience.
If you are new, everything is difficult. But if you read that something is simple you know that, even though for you right now it isn't, it will be in the future.
If you have issues with that simple task, maybe you are doing it wrong and should ask for help. On the other hand, if the documentation says that something is hard, you shouldn't even attempt it as a beginner, and perhaps wait until you have more experience.
> If you have issues with that simple task, maybe you are doing it wrong and should ask for help.
Far more common, in my experience, is that the author considered it so simple they did not spend any effort explaining it adequately. I.e. they were so distanced from their target audience (by virtue of their amassed experience) that they forget to adapt the text for them.
There are other, more descriptive ways to explain that things are more or less complex for experienced users.
Far more common, in my experience, is that the author considered it so simple they did not spend any effort explaining it adequately. I.e. they were so distanced from their target audience (by virtue of their amassed experience) that they forget to adapt the text for them.
There are other, more descriptive ways to explain that things are more or less complex for experienced users.
If simple things like running a command isn't simple for you then the docs were written for a different target audience than you. Just because I'm checking the docs it doesn't mean that something isn't simple. It is just impossible for me to know or remember everything about everything even if some of those things are simple.
If you aren't the target audience that doesn't mean you can't use it, you just might end up needing to ask for help from someone who is from the target audience.
If you aren't the target audience that doesn't mean you can't use it, you just might end up needing to ask for help from someone who is from the target audience.
Indeed. Or, put differently, proclaiming things to be "easy" in your documentation mainly serves to scream "go away!" to new users.
The problem isn't the word "simple" it's words like "just". Within something complex, there can be a simple thread of reasoning that may not be easy to see and once communicated, everything takes shape and begins to make sense. That's worth communicating even if it's not easy to describe. Often that may be how the author came about the design. I wouldn't know how better to describe such a thing. Explaining all the complicated things that make the simple thing work ends up with the reader being able to agree with all the explanations, then wonder "yeah, but why do those all add up to do what it does?"
Tone of writing is important, but also a reader shouldn't assume that something that has a simple core is easy to make or later understand. I'd say it's more constructive to have your docs show how/why it's simple rather than make a statement and leave it up to the reader to piece it together.
What's a better word than "simple" that doesn't make it also imply "easy" to many? e.g. the elevator thought experiments of General Relativity are simple, but not easy to come up with or initially reconcile.
Tone of writing is important, but also a reader shouldn't assume that something that has a simple core is easy to make or later understand. I'd say it's more constructive to have your docs show how/why it's simple rather than make a statement and leave it up to the reader to piece it together.
What's a better word than "simple" that doesn't make it also imply "easy" to many? e.g. the elevator thought experiments of General Relativity are simple, but not easy to come up with or initially reconcile.
This is just yet another politeness law, adding some more words we shouldn't use. There is a useful message though: make writing clear and unadorned.
> There is a useful message though: make writing clear and unadorned
I think this is the key takeaway. From the example in the article, phrases like 'just', 'painfully simple', 'just another way' aren't instructive nor objective, but decorative and subjective.
Documentation should have exactly one purpose: to instruct. There ought to be no mentions of difficulty, or obviousness, or triviality, or any other smart-aleck commentary. It ought to have a direct, clear tone, such as 'do X, which causes Y. Now do A and B, which requires C.' and so on.
I think this is the key takeaway. From the example in the article, phrases like 'just', 'painfully simple', 'just another way' aren't instructive nor objective, but decorative and subjective.
Documentation should have exactly one purpose: to instruct. There ought to be no mentions of difficulty, or obviousness, or triviality, or any other smart-aleck commentary. It ought to have a direct, clear tone, such as 'do X, which causes Y. Now do A and B, which requires C.' and so on.
I see it differently. If you are writing documentation for a system you know a lot about, things are completely simple for you right then right there. But as we all know in 6 months you'll look at your own code and think "who the ... wrote this?".
So avoiding the word "simple" isn't about accommodating the 5% of your least intelligent users and dumbing down the content, but the > 90% who are not so into the topic as you are right now.
So avoiding the word "simple" isn't about accommodating the 5% of your least intelligent users and dumbing down the content, but the > 90% who are not so into the topic as you are right now.
Clarity, yes. But not specific rules. Or we're back to the Plain English Campaign simplistic "only write in the active voice" silliness.
This reminds me of my time at Amazon where it was hammered into us to avoid weasel words: https://www.factoftheday1.com/p/amazon-writing-style-tip-3-1...
Eliminate anything like "just" and vagaries like "simple."
Eliminate anything like "just" and vagaries like "simple."
Even further nowadays, docs are created using Docusaurus. I don't have problem with it but documentation should be good (eye) friendly than easy to write. Why not be creative while writing docs such as -
Backbone.js - https://backbonejs.org Or https://backbonejs.org/docs/backbone.html as code annotation. jQuery - https://api.jquery.com/ Bootstrap v3.x - https://getbootstrap.com/docs/3.4/ Go docs - https://pkg.go.dev/std
Backbone.js - https://backbonejs.org Or https://backbonejs.org/docs/backbone.html as code annotation. jQuery - https://api.jquery.com/ Bootstrap v3.x - https://getbootstrap.com/docs/3.4/ Go docs - https://pkg.go.dev/std
Given the state of software documentation in general, I am okay with any word choices the author wants to use, even the downright offensive, as long as it means they actually document the software thoroughly. I have way bigger fish to fry than the emotional response I have (or don't have) to a given word.
This is a new rephrasing of an older mantra, which is to use fewer words when possible. The writings of the greats in our field exude this quality, for instance those of Dennis Ritchie. Mind you, he does use the aformentioned words, but they are often necessary, for instance, using the wording "simple shell" is true, because the shells he developed were indeed simpler than the ones before, and provably so.
The only twist in this new take is that it has an issue with commanding language using such words, and I agree. If you are telling me how to do something, there is no need to qualify the effort, because you don't have that information and neither do I, so the language ends up being verbose and, more crucially, incorrect.
The only twist in this new take is that it has an issue with commanding language using such words, and I agree. If you are telling me how to do something, there is no need to qualify the effort, because you don't have that information and neither do I, so the language ends up being verbose and, more crucially, incorrect.
Now that I've written a few specifications (which tend to have a much higher explanatory burden), I've come to appreciate just how difficult it is to write introductory material to a subject that you're an expert in. Like any skill, it takes a lot of practice.
Lol, yeah the first time I attempted it, someone got so frustrated they posted an expletive laden issue on the repo. There’s some real latitude to go wrong here!
I don't share the author's POV describing this sort of thing as "infuriating" or anything else that dramatic, but the before-and-after documentation example was definitely more readable and clear (I've never worked with rails [ruby?]).
So I support the overall premise here. It's nice to read documentation that is at least verbose enough to give you additional keywords to search with if you need more help, and I do feel a little bit more respected as a user when it feels like someone took time and care to write the docs with juniors in mind.
I think that a lot of the tutorials available on Digital Ocean are actually good examples of this; though they're not "docs" per se.
So I support the overall premise here. It's nice to read documentation that is at least verbose enough to give you additional keywords to search with if you need more help, and I do feel a little bit more respected as a user when it feels like someone took time and care to write the docs with juniors in mind.
I think that a lot of the tutorials available on Digital Ocean are actually good examples of this; though they're not "docs" per se.
> a lot of the tutorials available on Digital Ocean are actually good examples of this
Second this (although the qualities of DO’s tutorials can vary greatly). Indeed, their “Technical Writing Guidelines” [1] agree with the author:
> We avoid words like "simple,” "straightforward,” “easy,” “simply,” “obviously,” and “just,” as these words make assumptions about the reader’s knowledge. While authors use these words to encourage and motivate readers to push through challenging topics, they often have the opposite effect; a reader who hears that something is “easy” may be frustrated when they encounter an issue. Instead, we encourage our readers by providing the explanations they need to be successful.
[1] https://www.digitalocean.com/community/tutorials/digitalocea...
Second this (although the qualities of DO’s tutorials can vary greatly). Indeed, their “Technical Writing Guidelines” [1] agree with the author:
> We avoid words like "simple,” "straightforward,” “easy,” “simply,” “obviously,” and “just,” as these words make assumptions about the reader’s knowledge. While authors use these words to encourage and motivate readers to push through challenging topics, they often have the opposite effect; a reader who hears that something is “easy” may be frustrated when they encounter an issue. Instead, we encourage our readers by providing the explanations they need to be successful.
[1] https://www.digitalocean.com/community/tutorials/digitalocea...
Give up 70% of the way into the hyperstitious slur cascade.
https://astralcodexten.substack.com/p/give-up-seventy-percen...
https://astralcodexten.substack.com/p/give-up-seventy-percen...
It's annoying and sometimes demeaning and often tactical when managers use it.
In docs it can be annoying when there's assumed knowledge and skills.
And it adds nothing except to indicate how another may find the activity--why bother adding it?
Simply improve your docs, people.
In docs it can be annoying when there's assumed knowledge and skills.
And it adds nothing except to indicate how another may find the activity--why bother adding it?
Simply improve your docs, people.
I think those words do convey useful information. If, for example, a student is told that a theorem has a simple proof, she will find it faster than if she does not possess that information, because the search space becomes smaller.
When I was in high school I did Moot Court. I remember our coach telling is to stop using the word "clearly" in our arguments. His point was that if it really was so clear you wouldn't be in court arguing about it.
“With fewer lines of code” is not the same thing as “simpler” - particularly, if it’s an abstraction that requires the user to understand the underlying mechanics, the more verbose code may be significantly more self-evident.
If you’re writing even an internal API and this thought pops into your mind, put yourself in the shoes of a junior colleague and ask yourself - or ask one directly! - if a little bit of boilerplate is actually a good thing.
And, to the OP’s point, if you do decide to make these abstractions, using terms like “brevity” rather than “simplicity” can be a big part of gaining adoption.
If you’re writing even an internal API and this thought pops into your mind, put yourself in the shoes of a junior colleague and ask yourself - or ask one directly! - if a little bit of boilerplate is actually a good thing.
And, to the OP’s point, if you do decide to make these abstractions, using terms like “brevity” rather than “simplicity” can be a big part of gaining adoption.
Not sure I've seen the sentence 'Setting this up is painfully simple.' used often in any documented instructions. It's unnecessary and rather arrogant.
please add "blazing fast" to this list
Preferably with zero benchmark or one with a clearly artificial setup.
Rock star ninja rocket emoji Rick and Morty gif
and anything and everything "unleashed"
> If someone’s having to read your docs, it’s not “simple”
The opening quote of the article is so stupid. If the docs are enough to teach you to use a tool, that seems quite simple to me.
The opening quote of the article is so stupid. If the docs are enough to teach you to use a tool, that seems quite simple to me.
My fav game with a new tool is to take "simple" features and break them on equally simple use cases that are not documented. The most popular libraries are with no surprise the ones that resist this game the best. To give example, I like React and Next.js new beta documentation because they do not stick to being a reference but also explain the rationale and show real-life usage as much as possible.
I think people say “just simply” because they’re proud of having reduced a boatload of complexity to a couple steps. It says implicitly, “If only you knew how much work I’ve saved you!”
Maybe there’s also an aspect of “customer service”, where the writer adopts the tone of a smiling amusement park tour guide. I can see a cheerful female intern writing docs like this. A no-nonsense Richard Stallman type, not so much.
Maybe there’s also an aspect of “customer service”, where the writer adopts the tone of a smiling amusement park tour guide. I can see a cheerful female intern writing docs like this. A no-nonsense Richard Stallman type, not so much.
It’s like when I was growing up, I always found it hilarious that the seller on TV touted a “low low price of ONLY xyz”, and they marveled at their own offer! As a kid, I realized that this is silly… it us the buyer who determines if the price is affordable or not. Most advertising in the last few decades just spouts nonsense in an effort to get you to buy something.
You’d be amazed how many people still watch this shit in 2023 and even buy it, when
1) you can quite easily* find what cheap product is this a rebrand of
*admittedly not so easily since Google became extremely enshittified in the last fiveish years
2) drop that product into any old ebay or a price comparison engine and marvel at the markups they rack
3) find reviews of the same and see how those products come apart when you look at them funny, or are made of plastics known to cause cancer wide outside California, or some shit
But then again, it’s my bubble, outside of it it’s far from “obvious”
1) you can quite easily* find what cheap product is this a rebrand of
*admittedly not so easily since Google became extremely enshittified in the last fiveish years
2) drop that product into any old ebay or a price comparison engine and marvel at the markups they rack
3) find reviews of the same and see how those products come apart when you look at them funny, or are made of plastics known to cause cancer wide outside California, or some shit
But then again, it’s my bubble, outside of it it’s far from “obvious”
Not that the commercials were this deep, but the ability to afford something by the buyer doesn't change the relative pricing compared to the market. If I throw a 3 bedroom house on the market in a HCOL area for $200k when every similar home is going for $500k, it's a perfectly truthful statement to say it's being sold for a "low low price of only $200k". The fact that is out of the price range of a part time fast food worker is irrelevant. Though it's probably worth using "low low price of only" as a marker to investigate why something is so much cheaper than it's market price.
They use it because it works on people with IQs that are average or below, even adults
> If someone’s been driven to Google something you’ve written, they’re stuck.
This is not true. When I evaluate new technology to decide whether to use it or not, I tend to Google or HN around to see what people think about it. The words "just" or "simply" can be a good expression somebody uses to express their opinion about the library.
This is not true. When I evaluate new technology to decide whether to use it or not, I tend to Google or HN around to see what people think about it. The words "just" or "simply" can be a good expression somebody uses to express their opinion about the library.
[deleted]
15 years of experience in web development. And I'm a tech leader but still have a hard time to understand Amazon S3 docs.
We simply delete the word simple and just remove the word just when we see it too.
Some similar simple writing rules that we've found just improve writing overall here [0]
https://styleguide.ritza.co/ritza%27s-writing-rules/Style/
Some similar simple writing rules that we've found just improve writing overall here [0]
https://styleguide.ritza.co/ritza%27s-writing-rules/Style/
The word does have some value though. I'd rather replace it by something that means "it's a popular way to do it", "it will help you to do it that way", or "it's recommended for beginners to use this procedure".
You shouldn't use "simply" because it's an adverb and an overused one, but this mumbo-jumbo about feelings is giving me the creeps.
The example given reads better because it cuts out the adverbs. I'm assuming Grammarly or something similar helped to lint it.
Such cringe.
The example given reads better because it cuts out the adverbs. I'm assuming Grammarly or something similar helped to lint it.
Such cringe.
Haskell believers should read this. Look at this recent response to "that's not simple, by definition alone":
https://news.ycombinator.com/context?id=35756937
https://news.ycombinator.com/context?id=35756937
+1 to the article.
I’ve noticed this more recently. Ironically, it seems to be more common with coding communities known for their welcoming spirit and helpful nature, for example Rust.
Gratuitous repetition of how easy something is can make it feel harder when understanding is not immediate.
I’ve noticed this more recently. Ironically, it seems to be more common with coding communities known for their welcoming spirit and helpful nature, for example Rust.
Gratuitous repetition of how easy something is can make it feel harder when understanding is not immediate.
I think it's more common in technical communities trying desperately to persuade people that their obscure low-level tech is not as obscure and low-level as it actually is -- for example Rust (but also Linux, C/C++, BSDs, networking, etc).
The post is right: if you're explaining something, it's because the other person could not understand it without help, which means it's not, in fact, easy. It might be easy to repeatedly use it once you understand it, but it's not easy to grasp in the first place - otherwise you wouldn't have to be there in the first place.
The post is right: if you're explaining something, it's because the other person could not understand it without help, which means it's not, in fact, easy. It might be easy to repeatedly use it once you understand it, but it's not easy to grasp in the first place - otherwise you wouldn't have to be there in the first place.
also available in pandemic-remote-conference-talk format: https://brightonruby.com/2020/just-simply-emma-barnes/
Agreed. I've submitted PRs removing the word "simple" from docstrings. If you find yourself writing "This is a simple wrapper around...", what you meant to write is "This is a wrapper around...".
Check this out:
https://github.com/search?q=%22simple+yet+powerful%22
Biggest clichéd phrase out there in marketing to developers.
https://github.com/search?q=%22simple+yet+powerful%22
Biggest clichéd phrase out there in marketing to developers.
If you configure your Grammarly in formal mode (i.e. documentation), it will automatically suggest removing almost all of these words. The purpose is to reduce verbosity.
How about we stop telling people how simple, fast, efficient or whatever our software is. Let users decide for themselves. Tell them what it does and how to use it.
I agree that words like simply and just should not be used in documentations, but are people really getting upset about it? I couldn't imagine being this fragile
Learning tech through documentation is hard for some people.
People who try to make something easy by force of "magic words" is pretty common in the tech industry.
People who write the docs likely do not want the reader to feel stupid.
This is low hanging fruit and good advice. No one is screaming or fragile here.
People who try to make something easy by force of "magic words" is pretty common in the tech industry.
People who write the docs likely do not want the reader to feel stupid.
This is low hanging fruit and good advice. No one is screaming or fragile here.
Think a little harder, then. It was written for a reason. They even bought a domain and hosted this one page, for a reason. You think they did all that because they were fragile?
...maybe? Why would fragility be a less likely explanation? I promise, I'm thinking as hard as I can but maybe I'm too dumb.
These are excellent before-after example pair I can ask GPT to analyze then apply the technique to my own writings. I hope there are more examples like this.
...unless it's actually simple. Unfortunately a lot of software these days (especially the "modern" stuff) does not qualify.
Yes, often it's used for things where you "simply" have to install a dependency which does so much stuff its official website can't tell you what it is, then you have to figure out how to install precisely version 3.9.7 because another one won't work for this, and of course use that one workaround to initialize it the first time, and you're set unless one of the 10 git clones in some script fails.
Many things could instead be as simple as "python main.py".
Many things could instead be as simple as "python main.py".
It’s very difficult to tell what is actually simple
This describes a trivial way to improve your documentation, by simply just eliminating words like “easy” and “straightforward”.
(I agree with TFA.)
(I agree with TFA.)
Yes. It's a subset of removing noise words. Like excising "like" from speech. Or not starting sentences with "So...". "Obvious" should also be on his specific list.
This is
really annoying
to read
on my
relatively small
phone screen.
There is
way too
much whitespace
and only
about 4
words per
line.
really annoying
to read
on my
relatively small
phone screen.
There is
way too
much whitespace
and only
about 4
words per
line.
Simply get a computer.
Did this article really deserve its own domain?
People can get domains for whatever they want, you don't need to earn them.
one down [checks account on dnsimple.com] 59 to go...
Indubitably.
[This library] makes it even harder to [do difficult thing] I will suffer you through it, at the end you will hate me, be more confused and have even less of an idea how to use [this library]
[Complicated thing] made more complicated and harder.
I will have you do many difficult things and remember them just to do [difficult thing].
Good luck, you are going to need it!
Good luck, you are going to need it!
Reminds me of the turbo encabulator presentation [1].
Quote: "The latter consisted simply of six hydrocoptic marzlevanes, so fitted to the ambifacient lunar waneshaft that side fumbling was effectively prevented."
[1] https://www.youtube.com/watch?v=Ac7G7xOG2Ag
Quote: "The latter consisted simply of six hydrocoptic marzlevanes, so fitted to the ambifacient lunar waneshaft that side fumbling was effectively prevented."
[1] https://www.youtube.com/watch?v=Ac7G7xOG2Ag
I personally only use heavy-weight, slow, complicated and hobby grade JavaScript.
While we’re at it, let’s stop saying “add additional“.
“Add” means the same thing
“Add” means the same thing
"Add milk to that cereal" vs "Add additional milk to that cereal"
If that was all I heard of a conversation from the other room, I would form two different ideas of what was going on in that room, hence they can't mean the same thing.
If that was all I heard of a conversation from the other room, I would form two different ideas of what was going on in that room, hence they can't mean the same thing.
I cheerfully confess that you are right. I also assert that this would be a tiny minority of uses where this would make sense.
Did they really buy a whole domain to host one short op-ed?
I've got to do something with them...
Offtopic but i wish devs would offer light theme too.
cough cough Spring cough cough
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?