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

221–230 of 299 posts

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

#221

Post by jonahx »

crazygringo wrote: post #205
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…

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

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.

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

#222

Post by samtho »

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…

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.

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

#223

Post by dingledork69 »

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…

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.

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

#224

Post by alwaysbeconsing »

Frost1x wrote: post #150
zemo wrote: post #125

Earlier quoted context omitted.

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…

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.

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

#225

Post by vinaypai »

has_many_books wrote: post #111
vinaypai wrote: post #80

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

It wasn't an example: it was copied and pasted from the Rails guides at the time.

Oh wow, okay. That sounded so bad I didn't think it could possibly be from the real documentation for a pretty popular product.

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

#226

Post by ianbutler »

thunky wrote: post #190
ianbutler wrote: post #179

Earlier quoted context omitted.

I A. Don't see significant similarity between welding and programming B. Think that you would be wrong about people being annoyed about things that make their work harder across any time period. The difference is how people expressed those emotions or not, not whether they had them.

> The difference is how people expressed those emotions or not That's a change in behavior.

> It's not possible that the average modern software developer is just a bit more sensitive about their work than a welder was in 1950?

I was responding to this. My answer is no. Whether they express it or not, I imagine the sensitivity hasn't increased. You can feel something (being sensitive) without choosing to express it.

Emotional control is something well-adjusted people do every day, regardless of what they are feeling. It is simply more acceptable to express these emotions now.

If I had to guess people in the 50s just died inside and then drank themselves to death instead. Or took it out on their families.

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

#227

Post by tomlogic »

dingledork69 wrote: post #223
zemo wrote: post #125

Earlier quoted context omitted.

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…

If you don't understand something then you're in the perfect position to improve the docs. Others who are already familiar with the project may not think they need to document it, because they see it as simple.

This is an important lesson. Anytime you're onboarding a new user/employee, your documentation will benefit by getting that person's feedback. What's incorrect? Where there any steps that weren't clear? Or missing steps? Is there information that's outdated?

I've even gone as far as forcing the developers to answer questions by incorporating new information into the documentation. If you start having out-of-band communication (email, chats, in-person conversations) between the newbie and the team, there's a strong chance that extra information will never find its way back into the documentation.

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

#228

Post by spondylosaurus »

bityard wrote: post #194
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…

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…

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.

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

#229

Post by mdaniel »

beepbooptheory wrote: post #121

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

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

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

#230

Post by yieldcrv »

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…

> 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

Post reply on HN