Hacker News Reader

Comment by adekok | Hacker News Reader

Having written documentation for end users, that will work for only a portion of them. Probably most, which is good.

But there are a significant percentage of users who can't (or won't) read documentation. Even they do manage to read it, they don't understand it.

For some reason, human interaction works better for those people. They ask a question, and someone copies the answer from the documentation, and pastes it into the chat conversation. The user then goes "Oh, wow! That's helpful!"

But ask them to read a web page, and they get lost.

I would love to know the psychology behind this phenomenon.

View on HN

Similarly, I know people who are incapable of communicating information via email and insist that they must talk on the phone or in person.

Situation 1: "Hey can you call me?" Sure, what do you need to talk about? "The status of the Spark server." Okay.

Find a quiet place, place the call, debug connection problems so we can hear each other.

So what do you need? "Is the Spark server up?" Yes. "Okay, thanks, bye."

Situation 2: Email to coworker: "Hey the other day you said you said that the downloaded certificate is one factor, so with the password, that's already two factors, and the rotating token would be three. But we only need two, so that would mean we don't need the rotating token now. But the CTO is confused then -- how was the certificate securely transmitted in the first place, to the point that we can count it as a second factor?"

Two days later: Coworker approaches me: "So what was that email about?"

(Only exaggerating a little bit.)

To be fair, that is one hell of a poorly written email. HemingwayApp flags 2 of the 3 sentences as hard or very hard to read.

You honestly think it's very poorly written? You can't get any meaning from it, and believe that to be true even if you knew the context? You don't even have enough for a clarifying question?

I can show you writing a lot worse than that!

I can get some meaning out of it. If I knew the context, I could get more.

May I suggest running it through HemingwayApp[1] yourself and seeing that this particular email is objectively hard to read?

Write emails (and internet comments) like the reader is a drunk 7 year old. That's about as much attention as they're giving your email.

[1] http://www.hemingwayapp.com/

You're not answering the question. What specifically is hard to understand? Formulas are just heuristics, not some ironclad objective proof of illegibility. Ironically enough, across two comments, you haven't been able to convey such substantiation.

You also haven't explained what makes it horrible rather than so-so, which is important, since it's fairly easy to make it worse. You really can't just count words and dots and call it a day.

And if someone isn't going to read an email, but ask you to repeat it verbally, they really don't belong in an office environment. I'm sure that doesn't describe you!

Specifically these two sentences are hard to understand:

     Hey the other day you said you said that the downloaded certificate is one factor, so with the password, that's already two factors, and the rotating token would be three.

     But the CTO is confused then -- how was the certificate securely transmitted in the first place, to the point that we can count it as a second factor?

They are complex sentences. This makes them hard to understand.

The email's reading level is at grade 11 on the Flesch-Kincaid scale. [1] Anything above 9 is considered "Fairly difficult to read". Best selling authors tend to score less than 9. A lot less.

You don't need to write emails like you were a best selling author of course. That's silly. But it helps if you write them for the recipient. Don't just word vomit your train of thought.

Here's how I'd write your email (from what I can guess/understand of the situation):

     Hey,

     The other day we talked about auth factors in our app. You said the certificate was one factor.
     Adding the password, that makes two. A rotating token would make three.

     Do we really need the rotating token, then?

     But the CTO is confused: how do we know the certificate transmitted securely? It can't be an auth factor if we're not sure.

     Cheers,
     ~Bla

That said, we have way over-analyzed your email :)

[1] https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readabi...

[2] https://contently.com/strategist/2015/01/28/this-surprising-...

I had to read the email twice to understand it. It's absolutely hard to read.

At a minimum, each sentence is doing too much.

My lead is like that. When I send him instructions on how to do something, he always asks me to sit with him and walk him through them rather than attempting to follow them and then asking questions if he gets stuck.

> I would love to know the psychology behind this phenomenon.

Laziness. It's usually faster to ask someone a question than to look up the answer. I used to do this on IRC when learning a new programming language and it saved me a lot of time. If you want an even faster answer, you guess the wrong answer and wait for someone to correct you (https://meta.wikimedia.org/wiki/Cunningham%27s_Law).

It might not apply to you, but in my experience, people that ask questions that would faster be answered by google never actually learn the topic they're asking about. I think 90% of my knowledge was stumbled upon while looking for the answer to something else.

Sure, you might get the answer that X is the best way to do what you're trying to do, but if you read the docs, you might learn that what you're trying to do with X is already implemented and you can skip all that and just use Y. ( you not meaning you specifically here, just in general. )

> Laziness. It's usually faster to ask someone a question than to look up the answer.

My common answer is "If you're too lazy to read the documentation, I'm too lazy to cut & paste it into the email".

Followed by them complaining about how I'm an asshole...

I did this with my brother. Would always ask me beginner programming questions instead of getting Google-fu (while running a business making FileMaker Pro integrations, ugh).

Eventually I LMGTFY. He stopped asking.

I bitly my LMGTFY. The passive/aggressive nerd Rick Rolling.

That's gold. I'm going to use that one next time.

I don't think that fully explains it.

On my school's forum, people routinely ask questions which a simple Google search would have answered.

Yet typing out a question and posting it to a forum is a lot more work than searching on Google. I'd think the lazy response would be to stick to Google.

I often suffer from this - and it stems for me from apparent time pressure and or resentment.

The time pressure is the source of all sorts of sub-optimal issues - "I don't have time to write tests, documentation, do the right thing here ... Whatever. Including reading around the subject"

I do think modern corporate culture contributes to this - I remember being impressed by a PhD DSP guy who was in my scrum stand up who most days would report "I was reading yesterday and will be reading today". Every so often he would say "I finished reading and wrote ten lines that solved the problem"

As a contractor I felt I could not take a similar response, but I should ... or at least should be "I will be refactoring our Dbase access code / Our API / whatever cos it sucks rocks"

But I am weak.

Oh and resentment - "I don't want to find out the details of the pointless process this pathological bureaucracy has created and I really don't want to read a badly written set of documentation that probably does not have the real answers in it because no one likes to write the honest answers"

Hmm, glad it's Friday. I am worse than usual

In this specific instance, I wonder if some people, when panicking about their courses or under a deadline, are comforted by the notion that a TA is out there and willing to help them.

Sometimes this is about having a different learning style. Some people may absorb information better one on one. Tutoring and mentoring can be super helpful.

Another thing you might consider is that there are class and cultural factors to people's expectations about how you get along in life. Person to person conversation and personal relationships are important resources if you are working class or living in poverty.

There is a flip side to culture that disdains just asking, which is that smart people sometimes scramble to find answers independently to any questions because they don't want to reveal their ignorance on a subject. Sometimes just asking is not lazy, it is efficient and results in better collaboration as other people hear the question and realize they don't know, either, and would like to. Or, if no one knows, then you at least know have that information and can work from there.

Is the documentation going the be available via a chat bot or a web page? My guess is the second.

Screw the lazy users who won't look up documentation. If you can't read docs (he is a computer science professor), then do you really aren't in the right subject.

I would love to see email support go beyond that, and actually read the question... I hate when I get a canned response that is completely wrong, or doesn't apply.

Reply on news.ycombinator.com