[ryangittins]

This is an interesting point! I do think there's another factor at play here, though: documentation goes stale.

When you've been burned by stale documentation (or any tool) enough times, you can start to lose trust in it. When you lose trust in documentation, you second-guess it and often pursue a a live, fresh second opinion from another developer with more knowledge anyway.

[aequitas]

And that developer gets fatigued by constantly having to tell others to RTFM, because the documentation is up to date and comprehensive, he took his damn well time to make it so, if they just also took their time to read it, but instead they always ask him anyways or he has to point everything out and at a certain point they just don't care anymore.

[ryangittins]

It's very true. I think in reality it tends to be a mix—sometimes documentation goes stale, and sometimes people don't even bother reading it regardless of whether or not it's stale.

Another large problem is developers not knowing what they're looking for. Documentation tends to solve the "how I do use this" question and not the "do we already have a solution for this" question.

I'm still not sure how to solve the problem of discovery outside of telling people, "read the docs and hope that someday you'll remember the relevant bits when you need to."

[thu2111]

Poor reading speeds and skills are a huge problem. I've wirken with even supposedly senior developers who will not read the user guide for some complex piece of software before trying to use it or even worse, mouthing off about how it doesn't have feature X so task Y will be too difficult so we should switch to an alternative! The user guide in this case was comprehensive and fresh.

The reality is, this sort of behaviour isn't penalised or shamed. Said developer got called out in a meeting with many others present and didn't even appear to feel embarrassment or apologise. Makes it tough to get people to write and take pride in documentation when that sort of thing happens.

[ryangittins]

I don't disagree that someone not reading the user guide is annoying, but I vehemently disagree than penalizing or shaming is appropriate in any professional workplace.

I would not want to work with anyone who thinks public shaming is right or even effective. It kills morale, makes people fear asking questions, creates a low-trust environment, and frankly is just plain rude.

[giardini]

He said "Said developer got called out in a meeting with many others present and didn't even appear to feel embarrassment or apologise."

In the noted case there was no overt penalizing (at least that we heard about) nor was there shaming (the person was apparently "unshameable"). Therefore your post falls short of it's target.

That said, in general, I agree with every word you said. I especially like the "frankly [it] is just plain rude." - good manners (etiquette) can make a world of difference in a workplace but have largely fallen by the wayside in our culture.

[ryangittins]

The "got called out in a meeting with many others present" part is something which I don't think should have happened at all—regardless of whether or not the developer in question felt shame. No good can come from publicly calling someone out in a meeting like that. It's childish and unprofessional.

I feel the best courses of action are to remind the developer privately and/or to make a general "remember to read the docs" statement to the whole team in the meeting.

[ledauphin]

both of these things happen all the time at my job.

new folks will show up and start complaining that "stuff doesn't work", at which point I will ask them to read the many READMEs that been sitting right in front of them.

Later, they will say "this documentation is wrong", where inevitably someone else changed some code but didn't change the documentation that is colocated with it.

Because the docs were wrong, nobody will read them next time. And the cycle continues.