[HN Gopher] Just Simply - Stop saying how simple things are in o...
___________________________________________________________________
Just Simply - Stop saying how simple things are in our docs
Author : cbracketdash
Score : 404 points
Date : 2023-04-30 03:26 UTC (19 hours ago)
(HTM) web link (justsimply.dev)
(TXT) w3m dump (justsimply.dev)
| vinaypai wrote:
| 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.
| has_many_books wrote:
| It wasn't an example: it was copied and pasted from the Rails
| guides at the time.
| vinaypai wrote:
| Oh wow, okay. That sounded so bad I didn't think it could
| possibly be from the real documentation for a pretty popular
| product.
| has_many_books wrote:
| I know: bonkers!
| Waterluvian wrote:
| 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.
| nelsondev wrote:
| +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.
| toyg wrote:
| 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.
| beepbooptheory wrote:
| 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...
| mdaniel wrote:
| > 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)
| layer8 wrote:
| This describes a trivial way to improve your documentation, by
| simply just eliminating words like "easy" and "straightforward".
|
| (I agree with TFA.)
| mhb wrote:
| 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.
| karmakaze wrote:
| 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.
| EVa5I7bHFq9mnYK wrote:
| 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.
| throwaway14356 wrote:
| [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!
| charcircuit wrote:
| 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.
| tremon wrote:
| Indeed. Or, put differently, proclaiming things to be "easy" in
| your documentation mainly serves to scream "go away!" to new
| users.
| wouldbecouldbe wrote:
| 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.
| gumby wrote:
| 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.
| rusl1 wrote:
| 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.
| _RedPanda wrote:
| 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
| lucidguppy wrote:
| 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.
| throwawaaarrgh wrote:
| 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?
| infinitezest wrote:
| ...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.
| Myrmornis wrote:
| 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...".
| mistercow wrote:
| 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."
| ho_schi wrote:
| Germans here? Klicken sie einfach auf
| "Ausfuhren". Click simply on "Execute".
|
| The writers of manuals love the word "simply". There is just one
| problem:
|
| 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.
| lnxg33k1 wrote:
| 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?
| meotimdihia wrote:
| 15 years of experience in web development. And I'm a tech leader
| but still have a hard time to understand Amazon S3 docs.
| tarkin2 wrote:
| 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.
| codeflo wrote:
| Or maybe -- controversial opinion here -- people shouldn't be
| such babies. I'm looking around the HN discussion here and can't
| quite believe how personally offended people are by these words.
|
| Yes, at the beginning of the first semester at university,
| hearing a math professor say a step is "trivial", when it was
| quite hard, was a bit grating. One month in, I realised that the
| intended meaning of the word was that no special clever trick was
| required to make the deduction, just a lot of perseverance.
|
| Similarly, when documentation mentions to "simply" do something,
| and I don't get it, isn't that a clear hint that I'm still
| missing a concept somewhere and need to look around for an
| explanation?
|
| What I wonder is: Why is this so personal? Are people really
| shamed into quitting their career over a misplaced "simply" in a
| piece of tech writing because it triggers their impostor
| syndrome? Is that the reason why tech documentation has slowly
| been evolving into 50-minute step-by-step YouTube tutorials that
| start with installing the IDE? What happened to the expectation
| of people being adults?
| vrnvu wrote:
| I agree with your point. Nowadays, people seem to be overly
| sensitive about their code and the way we communicate, among
| other things.
|
| It's important to remember that the code is not a reflection of
| ourselves, and not everyone will be pleased with it. Some will
| provide good guidance, while others will not. Therefore, we
| should remove our ego from the code. Code is like a lollipop
| that we enjoy, but then discard once we're done with it.
|
| If I don't understand a design doc, it doesn't necessarily mean
| that I'm stupid or that the writer is bad at communicating. It
| may simply require more effort on my part to fully comprehend
| it.
|
| I don't understand why some people are so sensitive and take
| everything as a personal attack.
| rco8786 wrote:
| > Nowadays, people seem to be overly sensitive about their
| code and the way we communicate, among other things.
|
| If there's one thing I've learned in life, anytime you see
| "Nowadays" or "these days" or something similar, you can be
| guaranteed that whatever statement follows it is a universal
| truism about the human condition that recency has no bearing
| on.
|
| People are sensitive about their work. And sensitive to how
| we communicate together. Always have been. Always will be.
| thunky wrote:
| So you're saying people as a whole don't change behavior
| over time?
|
| It's not possible that the average modern software
| developer is just a bit more sensitive about their work
| than a welder was in 1950?
| ianbutler wrote:
| I've known people who talk about their welding skill and
| would be unhappy if you pointed out their joint looked
| like crap.
|
| People, in general, are sensitive about anything
| important to them.
| thunky wrote:
| I was trying to compare equivalent professions across
| time periods, not to suggest that welders are any
| different than developers.
|
| I would not be surprised if modern day welders get
| offended by their equipment manual as well.
| ianbutler wrote:
| 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.
| thunky wrote:
| > The difference is how people expressed those emotions
| or not
|
| That's a change in behavior.
| ianbutler wrote:
| > 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.
| adolph wrote:
| > 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...
| Kye wrote:
| 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.
| lamontcg wrote:
| 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.
| pjmlp wrote:
| 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.
| newswasboring wrote:
| 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]
| staunton wrote:
| 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(tm) 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.
| shri_krishna wrote:
| I agree with your take. To put it bluntly: snowflakes. That's
| what it is. These sort of expectations make it even worse for
| those for whom English is not a native language. Who already
| struggle to write documentation in English but now have to be
| mindful about tonality as well as not using words that might
| trigger some snowflake in some other corner of the World. Very
| unfortunate that people can get triggered by such trivial
| things.
|
| I once saw a video of how astronauts who visit the
| International Space Station had to learn Russian as everything
| in the Soyuz was labelled in Russian. Had to even read
| documentation written in Russian to be able to operate Soyuz
| optimally. None of these snowflakes would have survived such
| demanding jobs.
|
| One positive thing about AI revolution and ChatGPT is that we
| can finally get documentation automated out of the equation and
| introduce neutral language. This shouldn't even be a problem
| going forward. A prompt for "Important: rewrite this
| documentation in as non-offensive way as possible while
| blacklisting words such as 'just', 'simply'" etc should do the
| trick.
| jodrellblank wrote:
| The left: "X change would be better because Y".
|
| The right, having a meltdown about it: "I'm superior, you're
| snowflakes, you're pathetic babies, you're weak, I'm a real
| adult, I'm not afraid, you're triggered by everything, _blah
| blah_ ".
|
| Why does this happen? Why are you so insecure that
| _suggesting a way for documentation to be made clearer_ makes
| you conjour up a fantasy about an imaginary group of people
| who can 't learn Russian so that proves they're inferior to
| you?
| shri_krishna wrote:
| > The left: "X change would be better because Y". > The
| right, having a meltdown about it: "I'm superior, you're
| snowflakes, you're pathetic babies, you're weak, I'm a real
| adult, I'm not afraid, you're triggered by everything, blah
| blah".
|
| Bad analogy. It literally applies to the article itself.
|
| The left: Mailers are really just another way to render a
| view
|
| The right, having a meltdown over "just" and "simply":
| Remove "just" and "simply" else it will ruin my flow of
| thought and is "jolting" to read. It comes off as
| "condescending", is "upsetting" and "annoying"; removing
| "it doesn't put people off".
|
| ----------
|
| > Why does this happen? Why are you so insecure that
| suggesting a way for documentation to be made clearer makes
| you conjour up a fantasy about an imaginary group of people
| who can't learn Russian so that proves they're inferior to
| you?
|
| No where did I say anyone is inferior to me? I said some
| are snowflakes and get offended by the most random thing
| imaginable and there is no obligation to cater to
| everyone's whims and fancies. Who would have thought words
| like "just" or "simply" can offend anyone? But here we are
| discussing if words like "easy, painless, straightforward,
| trivial, simple and just" offend people or not.
|
| Also, the "imaginary group of people" are the ones we never
| hear about. We only hear about the successful ones who
| toiled their way to become what they wanted to become
| without whining about everything along the way. My limited
| point is: if you really want to whine, there are much
| better things to whine about than language/tone of
| innocuous words in the documentation.
| newswasboring wrote:
| Classifying anything which is mental health related as
| "snowflakes" has lead us to many toxic traits in the current
| society. I would encourage you to take a harder look at what
| you are advocating here. To me it looks like to you taking
| anyone else's feelings into consideration is wasteful. I am
| sorry, I would rather work with snowflakes than bricks.
| shri_krishna wrote:
| [flagged]
| Kye wrote:
| Apologies if this causes offense, but: you have a single,
| formidable paragraph with nine questions in it. This is a
| lot to put on a reader all at once. Consider breaking it
| up a bit. That many questions all at once can feel more
| like an interrogation, while good communication feels
| like a conversation.
| shri_krishna wrote:
| No offense taken. Appreciate your input.
| yieldcrv wrote:
| > 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
| wellpast wrote:
| 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.
| samtho wrote:
| 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.
| qwery wrote:
| 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 ...".
| a_techwriter_00 wrote:
| The psychology involved in the response you're wondering about
| is really quite simple to understand.
| Muromec wrote:
| >What I wonder is: Why is this so personal?
|
| Looking at example given at this page, before the edit -- it
| looks like whoever wrote the library is being proud of this
| little trick they just invented. Look, look, mailer is just
| another kind of a view! Appreciate how neat it is that we don't
| invent another high-level concept but reuse existing stuff in a
| slightly different way. This is personal. Example on the right
| skips this part and focuses on how to use things.
|
| Being proud of "this little trick we invented" is good ofc, but
| maybe it's place is in a conference talk or into video of
| something. Maybe whoever is reading the doc is not your mom and
| doesn't care right now.
|
| It's a bit of a cultural shift from a community of cool people
| showing cool stuff to each other to more "it's just a job" kind
| of attitude. If you aren't there to appreciate clever tricks,
| it's just noise.
| imgabe wrote:
| Nah we don't need to strip out every ounce of personality
| from something someone was kind enough to write and share for
| free. Anyone whose delicate sensibilities are so offended can
| just simply write whatever free library they're using
| themselves.
| spondylosaurus wrote:
| 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.
| WilTimSon wrote:
| 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.
| crazygringo wrote:
| First of all, you're exaggerating tremendously, as I don't see
| anybody "quitting their career" over documentation, and
| literally nobody is talking about impostor syndrome (in the
| article or comments here). You're seeing things that aren't
| there.
|
| But secondly, I think what you're writing is a great example of
| how their are two philosophies or ideologies of communication.
|
| One philosophy (that you seem to subscribe to) is that it's the
| prerogative of the speaker (writer) to communicate however they
| think is right, and it's the responsibility of the listener
| (reader) to do the work to understand it, and reponsibility for
| miscommunication lies with the listener. To use your words, the
| speaker doesn't need to "baby" the listener, and the listener
| is wrong to be "personally offended".
|
| But the other philosophy is that it's the responsibility of the
| speaker to communicate in a way that will be best understood,
| and it's the prerogative of the listener to note where the
| speaker's communication is unclear, misleading, frustrating, or
| offensive to the listener. It's the speaker's job to make a
| good faith effort to know their audience and communicate
| appropriately for that audience, and to apologize and rephrase
| when they make mistakes.
|
| Now, which one is right? Well, there is no "right". What there
| is is -- which one _serves you better as the speaker?_ Which
| philosophy will further your goals, which one will get you
| further in life?
|
| Well if your goal is to be able to get angry at
| listeners/readers who don't get it and feel smarter than
| others, by all means adopt the first philosophy. But if your
| goal is for your speech and writing to have the impact you want
| it to have, the second philosophy is going to be more
| productive for you. And calling people "babies" is about as
| counterproductive as you can be in terms of getting people to
| listen to you.
| jonahx wrote:
| This is a useful framing, and personally I learn hard toward
| the "speaker is responsible" strategy.
|
| With that said, I think a continuum is an even more accurate
| framing. If you are confusing your audience, it is probably
| your fault. But not necessarily. Some people won't make an
| effort, will be distracted, or will engage in bad faith. I
| see it as a negotiation in which you should be strongly
| _biased_ toward the audience being right.
| aschearer wrote:
| 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.
| zemo wrote:
| 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.
| dingledork69 wrote:
| 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.
| tomlogic wrote:
| 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.
| Frost1x wrote:
| 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.
| alwaysbeconsing wrote:
| 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.
| waboremo wrote:
| 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!
| zemo wrote:
| connotation exists, you know
| waboremo wrote:
| 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.
| zemo wrote:
| I read the article, you're refusing to see the forest
| through the trees.
| stjohnswarts wrote:
| 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?
| throwawaaarrgh wrote:
| I could tell you you're missing the obvious answer, but that
| doesn't help you understand the thing you're missing. I could
| tell you the YouTube tutorial that starts from scratch has a
| very simple and obvious reason why it starts there, that a lot
| of other people get that you don't. But that doesn't help you
| either. And I could tell you that infantilizing someone who's
| having a hard time understanding something is the opposite of
| adult, but that doesn't tell you why.
| peoplefromibiza wrote:
| > YouTube tutorial that starts from scratch has a very simple
| and obvious reason why it starts there
|
| what's the reason in your opinion?
|
| Because in my opinion a programming tutorial that starts from
| installibg the IDE is like a recipe tutorial that starts from
| how to use a gas stove.
|
| it should be two different tutorials, at least
|
| It is clearly important to understand how an IDE works, but
| that's the kind of knowledge that should be implied when you
| watch a programming tutorial.
|
| Otherwise you need to learn two things at the same time.
|
| Besides, IDE are usually complex enough that the two sets of
| skill don't overlap, so if the tutorial focuses on the
| programming and skims over installing the IDE, it is assuming
| that you can "simply" or "trivially" install an IDE such as
| Jetbrains Idea and be immediately ready to use it
| proficiently enough to learn something else with it, instead
| of fighting it to get things done. Which is usually the case,
| when I teach programming at work I focus on the programming
| using slides or some basic live coding using a very basic
| editor (vanilla sublime for example), because if I start
| using IDE features, people start making a lot of questions on
| how to do the things that I am doing that I don't even
| realize that I am doing them without even thinking about
| them, to the point that it becomes an IDE focused training.
| Showing that you can't take for granted that installing an
| IDE is a good starting point. It raises more issues than it
| solves.
|
| I'm quite sure it would have been much harder for me to study
| Italian literature while I was learning how to read.
| throwawaaarrgh wrote:
| 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.
| johnchristopher wrote:
| > 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 ?
| bityard wrote:
| 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.
| spondylosaurus wrote:
| 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.
| tetha wrote:
| > 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.
| Kye wrote:
| 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.
| pclmulqdq wrote:
| 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.
| yellowapple wrote:
| > 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.
| grog454 wrote:
| 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.
| MrJohz wrote:
| 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.
| SoftTalker wrote:
| 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.
| paulddraper wrote:
| Words have meaning.
|
| And 92% of the time, "just" or "simply" have no useful meaning.
| jonahx wrote:
| It's unfortunate that this is the top comment, because the
| "after" samples are clear improvements.
|
| This is good old-fashioned writing advice, no different from
| Strunk and White's "Omit needless words" -- just tailored to
| developer documentation where a handful of specific needless
| words flourish.
|
| The _main_ reason to remove these words is that they are
| fluffy, superfluous marketing speak.
|
| Do some people also find them condescending? Maybe -- I don't,
| but this is a side point.
| ulizzle wrote:
| It's an improvement because it cut out all the adverbs. The
| tone of the essay is an unmistakable virtue signal.
|
| It tries to correlate the virtue signal with quality
| improvement, which is either cringe or disingenuous.
| spondylosaurus wrote:
| 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.
| matsemann wrote:
| > _Why is this so personal?_
|
| It's simple to understand, really. How come you don't get this
| trivial thing?
| nickjj wrote:
| > 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.
| novok wrote:
| 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.
| jstummbillig wrote:
| 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.
| tomcam wrote:
| 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.
| raydev wrote:
| 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.
| lallysingh wrote:
| "Simple" reads "simple for me" (the author). That can be really
| frustrating at times.
|
| But the real sin here is wasting words on useless bullshit.
| Just get to the damned point. "Just simply" is 100% waste. I
| can replace "Just simply verb" with "verb" and the sentence is
| already better, without putting a bunch of emotional loading
| into the context of the discussion.
| ozim wrote:
| 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.
| bjornasm wrote:
| 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.
| kristopolous wrote:
| 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.
| civilized wrote:
| 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.
| abootstrapper wrote:
| 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.
| _gabe_ wrote:
| 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.
| smcl wrote:
| This is such a bizarre take. The post is about removing some
| unnecessary wording from technical documentation that doesn't
| add anything, and _as an aside_ can sometimes imply complex
| tasks are simpler than they are to the detriment of the app
| /library/service it's documenting. I have no idea why you'd
| think this implies some personal failing or that it is advice
| for "babies"
| warent wrote:
| Agree wholeheartedly.
|
| Most people are comfortable making incremental improvements
| in all our tools and comforts in life, so why should
| communication (the greatest tool of all!) be any different?
|
| We can make a knife with a better handle or keyboard with
| better shape, and it's called "ergonomic." Nobody claims
| someone being a _baby_ for wanting that.
|
| Meanwhile, a small suggestion to enhance how we handle
| communication is met with such severity and perceptual
| distortions, as though the ones making the suggestions are
| having some breathless emotional psychosis. Why?
| codeflo wrote:
| > 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.
| zabzonk wrote:
| 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.
| lowercased wrote:
| * 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?
| [deleted]
| zabzonk wrote:
| > 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
| avereveard wrote:
| > 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.
| nonethewiser wrote:
| > The post is about
|
| Please reread the comment you are replying to. He's talking
| about the hacker news comments.
| warent wrote:
| 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"
| cal85 wrote:
| 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.
| WesolyKubeczek wrote:
| 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.
| fdschoeneman wrote:
| I've never heard of anyone quitting because they objected to
| being told something which they find complicated is "simple,"
| so this seems like a straw man.
|
| I think a lot of people think about how best to teach
| complicated ideas. Maybe like me, they really aren't that
| smart, or even just feel like they aren't that smart, and when
| they read from an expert or an instructor or a professor that a
| thing is simple, that voice inside their head that is
| constantly telling them they're dumb or worthless gets louder,
| and they wonder if that vouce is right, and that the idea they
| are trying to understand is simple for people who aren't
| impostors and they should probably give up and shoot
| themselves.
|
| Your professor used the word "trivially" in a stupid way.
| Similarly, technical writers and instructors use "simple" in a
| stupid way. Objecting to stupid language from teachers and
| technical writers that makes them less effective at their jobs
| doesn't make me a baby any more than celebrating it makes you
| an adult.
|
| I don't think people who use words like this intend for their
| audience to feel stupid. But I don't see how they are helpful.
| gyranthology wrote:
| > 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.
| chrismorgan wrote:
| Good discussion in 2021 (249 points, 138 comments):
|
| https://news.ycombinator.com/item?id=27418577
| _throwawayaway wrote:
| Offtopic but i wish devs would offer light theme too.
| qznc wrote:
| 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.
| apricot wrote:
| 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.
| hnarayanan wrote:
| 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!
| JoeyBananas wrote:
| 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
| furyofantares wrote:
| 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."
| javajosh wrote:
| 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.
| ellisv wrote:
| 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.
| javajosh wrote:
| 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.
| Tade0 wrote:
| 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.
| steve_adams_86 wrote:
| 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.
| frou_dh wrote:
| Check this out:
|
| https://github.com/search?q=%22simple+yet+powerful%22
|
| Biggest cliched phrase out there in marketing to developers.
| ulizzle wrote:
| 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.
| perrygeo wrote:
| 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".
| imiric wrote:
| 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.
| BossingAround wrote:
| > 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.
| kazinator wrote:
| 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?
| abtinf wrote:
| In English, the math jargon term "simplifies to" means
| roughly "is equivalent to this less complex form". It does
| _not_ connote difficulty.
| kazinator wrote:
| It absolutely denotes difficulty. E.g. more machine
| cycles are needed to traverse the original expression
| tree that has more nodes.
| blacksoil wrote:
| > 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.
| aliasxneo wrote:
| 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.
| rikschennink wrote:
| Super frustrating.
|
| There's a lot of "just do x" in stack overflow answers as well.
|
| It "just" makes the reader feel stupid.
| jabradoodle wrote:
| 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.
| brunooliv wrote:
| 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.
| EdSharkey wrote:
| 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".
| bvinc wrote:
| 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".
| umanwizard wrote:
| Plenty of people now say allowlist and denylist instead of
| whitelist and blacklist.
| WesolyKubeczek wrote:
| Goodlist and ungoodlist.
| WesolyKubeczek wrote:
| Blocklist for me is a list of blocks, like the one you
| gather with badblocks(8) and then pass to fsck(8).
| eric-burel wrote:
| 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.
| vdm wrote:
| please add "blazing fast" to this list
| unsupp0rted wrote:
| Rock star ninja rocket emoji Rick and Morty gif
| euroderf wrote:
| and anything and everything "unleashed"
| BiteCode_dev wrote:
| Preferably with zero benchmark or one with a clearly artificial
| setup.
| antognini wrote:
| 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.
| desro wrote:
| 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.
| firexcy wrote:
| > 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...
| robertlagrant wrote:
| 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.
| delta_p_delta_x wrote:
| > 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.
| jtwaleson wrote:
| 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.
| robertlagrant wrote:
| Clarity, yes. But not specific rules. Or we're back to the
| Plain English Campaign simplistic "only write in the active
| voice" silliness.
| tomcam wrote:
| While we're at it, let's stop saying "add additional".
|
| "Add" means the same thing
| savanaly wrote:
| "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.
| patrickmay wrote:
| 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."
| bityard wrote:
| Did they really buy a whole domain to host one short op-ed?
| has_many_books wrote:
| I've got to do something with them...
| taeric wrote:
| 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.
| btown wrote:
| "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.
| calsy wrote:
| 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.
| Smaug123 wrote:
| 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.
| Uvix wrote:
| _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.
| chazeon wrote:
| 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.
| has_many_books wrote:
| also available in pandemic-remote-conference-talk format:
| https://brightonruby.com/2020/just-simply-emma-barnes/
| dale_glass wrote:
| 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
|
| Which is it? $ bin/rails --generate=scaffold
| --user=name --email=login
|
| Or: $ bin/rails --generate=scaffold
| --user=username --name=fullname --email=address
| --login=login_name
|
| Or: $ bin/rails --generate --scaffold=user
| --name=fullname --email=address --login=login_name
|
| Or what?
| seri4l wrote:
| 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.
| ekimekim wrote:
| 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: $
| bin/rails generate scaffold --user=NAME --email=LOGIN
|
| and an example usage would then be: $
| bin/rails generate scaffold --user=ekimekim
| --email=ekimekim@example.com
|
| As far as I'm concerned, for documenting command usage, there
| is no excuse not to use this scheme.
| teddyh wrote:
| > _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.
| vivegi wrote:
| Its trivial. The obvious solution is to just simply read the
| extremely friendly documentation. /s
| bombcar wrote:
| 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.
| teddyh wrote:
| 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).
| nickjj wrote:
| 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.
|
| Is "a" a sub-command of cp or is it data? Is "a" in the rm
| command data or a value for the -f flag?
| intalentive wrote:
| 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.
| nmca wrote:
| Give up 70% of the way into the hyperstitious slur cascade.
|
| https://astralcodexten.substack.com/p/give-up-seventy-percen...
| TrianguloY wrote:
| 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.
| tremon wrote:
| _and should ask for help_
|
| By... reading the documentation, for example?
| hooverd wrote:
| Simply find the relevant thread in the mailing list. Or just
| watch one of the author's talks.
| kqr wrote:
| > 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.
| Hendrikto wrote:
| 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.
| marginalia_nu wrote:
| Simply get a computer.
| paradox242 wrote:
| 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.
| WesolyKubeczek wrote:
| 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
| tristor wrote:
| 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.
| kstenerud wrote:
| 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
| lelanthran wrote:
| 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
| phkahler wrote:
| 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.
| userbinator wrote:
| ...unless it's actually simple. Unfortunately a lot of software
| these days (especially the "modern" stuff) does not qualify.
| alpaca128 wrote:
| 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".
| unsupp0rted wrote:
| It's very difficult to tell what is actually simple
| kstenerud wrote:
| 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.
| ModernMech wrote:
| 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!
| lucidguppy wrote:
| 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.
| schwartzworld wrote:
| > 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.
| sametmax wrote:
| 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.
| WastingMyTime89 wrote:
| "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.
| fnordsensei wrote:
| "Simple" vs "easy": https://youtu.be/LKtk3HCgTa8
| lucakiebel wrote:
| Ok, so at least I'm not the only one using simply that way
| WesolyKubeczek wrote:
| Monty Python's sketch "How to Do It" has some decades.
| kqr wrote:
| 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".
| sjrd wrote:
| 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.
| kqr wrote:
| This is indeed where I usually go. "Under condition X, it
| is simpler to Y" rather than "Under condition X, you can
| simply Y."
| sametmax wrote:
| 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
| everybodyknows wrote:
| 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.
| wdfx wrote:
| 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.
| Semaphor wrote:
| "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.
| Fnoord wrote:
| 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.
| wongarsu wrote:
| > 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
| adolph wrote:
| 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.
| BiteCode_dev wrote:
| 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.
| opan wrote:
| 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.
| latexr wrote:
| > This should be automatized by writing tools.
|
| iA Writer1 does it. It strikes out and greys out the words
| "simply" and "just" as part of its style check for fillers.
|
| 1 https://ia.net/writer
| Osiris wrote:
| 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.
| gv83 wrote:
| 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).
| EGreg wrote:
| 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.
| unsupp0rted wrote:
| They use it because it works on people with IQs that are
| average or below, even adults
| WesolyKubeczek wrote:
| 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"
| tpmoney wrote:
| 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.
| blueflow wrote:
| 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...
| flockonus wrote:
| 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.
| sametmax wrote:
| 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.*
| incone123 wrote:
| There's an explicit caveat on chat gpt: limited knowledge
| of the world and events after 2021. You're asking about
| 22.04.
| VWWHFSfQ wrote:
| Right so that why it's not useful for this
| incone123 wrote:
| Re-reading the gpp, I assume the arg confusion was true
| in earlier editions of Python so maybe worth seeing how
| it handles the question as applied to those earlier
| editions.
| KMnO4 wrote:
| GPT != Chat GPT, GPT-4, etc.
|
| It's possibly to ["just simply"] train a GPT on whatever
| corpus you want.
| sametmax wrote:
| 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.
| oldsecondhand wrote:
| GPT-3 is opensource. GPT-4 isn't.
|
| https://github.com/openai/gpt-3
| junon wrote:
| 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.
| latexr wrote:
| > 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_.
| dbsmith83 wrote:
| Using the word 'entirely' helps to remember the ending to
| avoid since it ends with it
| stavros wrote:
| What, like "butterfly"?
| sametmax wrote:
| Like "otherwordly", obviously.
|
| Never use "otherwordly" ph'nglui technical documentation,
| ngnah ymg' risk
| s[?][?][?]u[?]m[?]m[?]on[?][?]i[?][?][?]n[?]g[?][?]
| z[?]a[?][?]lg[?][?]o[?].[?][?]
| stavros wrote:
| It was a joke, obviously. They're called adverbs.
| rendall wrote:
| A joke has to be funny tho
| stavros wrote:
| Like a comment has to be insightful?
| sametmax wrote:
| Unlike mine, obviously. I'm very serious.
| rzzzt wrote:
| Avoiding "butterfly" when writing technical documentation
| sounds like a good advice.
| latexr wrote:
| https://en.wikipedia.org/wiki/Butterfly_keyboard
| BellsOnSunday wrote:
| C-h f butterfly
| loloquwowndueo wrote:
| The keyboard in your thinkpad 701C has a mechanism we
| affectionately call butter... oh never mind.
| rzzzt wrote:
| "Affectionately"?! One point for Slytherin!
| [deleted]
| Hendrikto wrote:
| > avoid "-ly" words
|
| I hope this isn't the actual advice you were given. They are
| called adverbs.
| junon wrote:
| 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.
| nohuck13 wrote:
| 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
| sorokod wrote:
| 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.
| Fnoord wrote:
| For non-native English speakers -ly is simpler than adverts.
| But simpler does not necessarily mean better long-term.
| umanwizard wrote:
| Why is it simpler? Are non-native English speakers less
| likely to know what an adverb is than English speakers are?
| I doubt it.
| Fnoord wrote:
| 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.
| commandersaki wrote:
| This is a rule in the Hemingway app: https://hemingwayapp.com/
| [deleted]
| vrglvrglvrgl wrote:
| [dead]
| why-el wrote:
| 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.
| commandersaki wrote:
| Did this article really deserve its own domain?
| lpil wrote:
| People can get domains for whatever they want, you don't need
| to earn them.
| ykonstant wrote:
| Indubitably.
| has_many_books wrote:
| one down [checks account on dnsimple.com] 59 to go...
| sixhobbits wrote:
| 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/
| BiteCode_dev wrote:
| 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".
| jmartrican wrote:
| cough cough Spring cough cough
| toyg wrote:
| 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.
| magwa101 wrote:
| [dead]
___________________________________________________________________
(page generated 2023-04-30 23:01 UTC)