Just Simply – Stop saying how simple things are in our docs

It’s noise not unlike those 1-hour long “Shopping TV” ads.

I’m not against using the word as ling as it’s put into some kind of framework which allows some actual assessment of these claims:

— Simple compared to what?

— What prior knowledge or skill is assumed?

— When does it stop being simple?

But since “simple” is being either used by authors deeply enamored with their brainchild, or as I said above, as a marketing (read: manipulation) tool, your chances of getting straight answerd are slim.

It's 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.

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.

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

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

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.

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

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

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

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

. . .

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

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

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

> One month in,

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

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

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

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

HOWEVER. Writing is its own craft, and requires a totally separate set of skills than your typical engineer-turned-technical-writer is generally equipped with. They tend towards considering only what they want the reader to do or think, not necessarily who the reader might be or what _they_ want to get out of the writing.

The main problems with the "just simply" writing are twofold:

1. The "just simply" words are completely unnecessary filler. Good writing is stripped of superfluous filler words. Writing with lots of filler words is harder to read because scanning, parsing, and then discarding them is additional cognitive overhead. This technology shit is hard enough as it is, save the flowery prose for your poetry.

2. As others have mentioned, the tone of the "just simply" writing comes off as condescending because it implies the author is considerably more knowledgeable than the reader, that the reader doesn't know anything about the topic at hand, and that the reader will somehow reach enlightenment once they are on the same level as the author.

It's not that I am personally offended by "just simply," it's just bad writing, and I won't read that kind of stuff unless I really have to.

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.

I think a lot of people think about how best to teach complicated ideas. Maybe like me, they really aren't that smart, or even just feel like they aren't that smart, and when they read from an expert or an instructor or a professor that a thing is simple, that voice inside their head that is constantly telling them they're dumb or worthless gets louder, and they wonder if that vouce is right, and that the idea they are trying to understand is simple for people who aren't impostors and they should probably give up and shoot themselves.

Your professor used the word "trivially" in a stupid way. Similarly, technical writers and instructors use "simple" in a stupid way. Objecting to stupid language from teachers and technical writers that makes them less effective at their jobs doesn't make me a baby any more than celebrating it makes you an adult.

I don't think people who use words like this intend for their audience to feel stupid. But I don't see how they are helpful.

Every time I've heard this sentiment in the corporate setting, it sets the ball rolling to create a culture that's hyper masculine and aggressive where people asking for help are seen as weak, unable, and shouldn't be "there". Okay, maybe not fully explicitly, but it influences discussions, how people communicate, and how reviews are laid out over time.

I'd argue that people claiming "people shouldn't be such babies" as the ones needing to be quarantined and separated out from making decisions that impact larger groups of people. It's clear that they can't put themselves in the shoes of others and know how to pull the best out of people.

>> "What happened to the expectation of people being adults?"

Adults discuss things like adults: with empathy, fair reading, and hopefully a little kindness. They don't call other adults babies for raising issues.

But secondly, I think what you're writing is a great example of how their are two philosophies or ideologies of communication.

One philosophy (that you seem to subscribe to) is that it's the prerogative of the speaker (writer) to communicate however they think is right, and it's the responsibility of the listener (reader) to do the work to understand it, and reponsibility for miscommunication lies with the listener. To use your words, the speaker doesn't need to "baby" the listener, and the listener is wrong to be "personally offended".

But the other philosophy is that it's the responsibility of the speaker to communicate in a way that will be best understood, and it's the prerogative of the listener to note where the speaker's communication is unclear, misleading, frustrating, or offensive to the listener. It's the speaker's job to make a good faith effort to know their audience and communicate appropriately for that audience, and to apologize and rephrase when they make mistakes.

Now, which one is right? Well, there is no "right". What there is is -- which one serves you better as the speaker? Which philosophy will further your goals, which one will get you further in life?

Well if your goal is to be able to get angry at listeners/readers who don't get it and feel smarter than others, by all means adopt the first philosophy. But if your goal is for your speech and writing to have the impact you want it to have, the second philosophy is going to be more productive for you. And calling people "babies" is about as counterproductive as you can be in terms of getting people to listen to you.

People rightly deduct style and professionalism points for this regardless of whether they're personally offended.

At worst they are targeted at the wrong audience. The writer doesn't actually know how knowledgeable or experienced the reader is.

So if you're a writer or you're simply (heh) writing docs for a library you're working on, and you're decent at this task so you take a moment to reflect on how your audience might read your writing, why would you use the word at all?

> is that the reason why tech documentation has slowly been evolving into 50-minute step-by-step YouTube tutorials that start with installing the IDE?

Instead of falling into the trap of "kids these days" short-sighted whining, perhaps consider that the barriers to creating and sharing content have never been lower. More content targeted at beginners seems like a natural conclusion to me, since it reaches the widest audience.

My view: the purpose of documentation is to help people achieve their goals using your tools. Do everything that helps this purpose and don't do things that don't help it.

Does the occasional "simply" help the purpose? I would say it almost never does. Telling users whether a step is simple is meta-commentary that distracts from the actual steps and is only useful if it helps people make decisions ("choose way X to do Y because it's simple"). People who sprinkle "simply" into documentation seem to rarely think about whether it serves a real purpose.

50-minute step-by-step tutorials are very useful when your goal is just to do that thing. This conforms to my view that tutorials and documentation serve the purpose of allowing people to achieve goals.

You might feel instead that there should also be some pedagogical goal. People who read your documentation should become smarter, think outside the box, learn patience and perseverance that is required for their craft, etc.

I think the real debate here is about this fundamental distinction of what purpose documentation serves.

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

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

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

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

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

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

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

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

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

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 ?

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

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

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

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

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.

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!

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

Many students think their grade is worse than it actually is, they think they're worse at math than they actually are or they think the course is harder than it really is

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

It’s crazy to say, but I think not hearing what was “obvious” would have helped me excel more in my classes.

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

I catch myself sometimes starting a sentence with "Obviously," and usually stop myself at that point and restart.

I'm all ok with tutorials and examples into the docs, but give some depth to them, not only breadth (or emojis).

iA Writer¹ does it. It strikes out and greys out the words “simply” and “just” as part of its style check for fillers.

¹ https://ia.net/writer

It's exactly the type of writing OSS authors don't like doing, and all the information is publicly available.

— an emoji-laden intro employing borderline UwU-speak

— jumping into API reference immediately after

— the reference is auto-generated with half of it being stubs, implying you should throw it away and just simply read the code

> I mean, is it rendering a view or isn't it?!

It is rendering a view, and both versions make that clear. There's no contradiction in the rewritten version.

I hope this isn’t the actual advice you were given. They are called adverbs.

Following its own advice, “entirely” can be cut without loss of meaning. Considering the replies you’re getting, perhaps a better way to phrase it in the future would be:

> eschew "-ly" adverbs.

That way it’s clear you’re referring to a specific subset of adverbs.

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?

- String literals should be in lowercase (because by convention commands, argument names, etc should always be in all-lowercase, eg. "git cherry-pick" not "git cherryPick" or "git CHERRY-PICK")

- Metavariables (stuff the user should fill in) should be in ALL-CAPS.

- Not as strictly adhered to but still useful, [optional part] and {repeatable part}.

So eg. your example might look like:

    $ bin/rails generate scaffold --user=NAME --email=LOGIN

    $ bin/rails generate scaffold --user=ekimekim --email=ekimekim@example.com

    cp a b
    rm -f a b c
    etc.

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.

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)

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.

By... reading the documentation, for example?

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.

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.

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

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”

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.

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.

Many things could instead be as simple as "python main.py".

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.