Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

justsimply.dev

Post reply on HN
Print view View original

141–150 of 299 posts

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

#141

Post by ianbutler »

thunky wrote: post #131
rco8786 wrote: post #96

Earlier quoted context omitted.

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

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?

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.

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

#142

Post by dbsmith83 »

latexr wrote: post #65
junon wrote: post #2

One of the best pieces of advice I learned in high school from an incredible English teacher: when doing technical, avoid "-ly" words entirely. It has always been solid advice and has rarely led me astray.

> when doing technical, avoid "-ly" words entirely. Following its own advice, “entirely” can be cut without loss of meaning. Considering the replies you’re getting, perhaps a better way to phrase it in the future would be: > eschew "-ly" adverbs. That way it’s clear you’re referring to a specific subset of adverbs .

Using the word 'entirely' helps to remember the ending to avoid since it ends with it

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

#143

Post by shri_krishna »

codeflo wrote: post #70

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 s…

[flagged]

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

#145

Post by wellpast »

codeflo wrote: post #70

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 s…

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.

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

#146

Post by qznc »

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.

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

#148

Post by imgabe »

Muromec wrote: post #88
codeflo wrote: post #70

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 s…

>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 skip…

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.

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

#149

Post by mhb »

layer8 wrote: post #140

This describes a trivial way to improve your documentation, by simply just eliminating words like “easy” and “straightforward”. (I agree with TFA.)

Yes. It's a subset of removing noise words. Like excising "like" from speech. Or not starting sentences with "So...". "Obvious" should also be on his specific list.

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

#150

Post by Frost1x »

zemo wrote: post #125
codeflo wrote: post #70

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 s…

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 tha…

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.

Post reply on HN