[pydry]

I think the author is missing a key part of why developers often don't like writing documentation but do like answering questions: replacement value.

A developer's compensation is based upon their perceived value (how much it seems like they are needed) and replacement value (how much would it cost to replace them).

A developer that answers questions gets a reputation for helpfulness - this increases their perceived value. Another person needing to go to them to ask questions increases their replacement value too - the more they become the go to person for info, the clearer it is that the company would lose out if it replaced them.

Written docs have almost the opposite effect. Writing amazing documentation doesn't tend to get you a reputation - mostly because it's so depersonalized (does anybody think about the person who wrote a quickstart guide?). It also decreases your replacement value - a fantastically documented project is a project that can be easily handed off to someone else.

I really think that humans get a buzz out of being helpful, too, and you just don't get the feedback that gives you that buzz by writing pages in confluence or whatever. You will likely not even know who found it useful, whereas the dopamine hit you get when somebody asks you a question and you answer it and they click the "heart" button on your slack message is instantaneous.

[erikerikson]

There's another perspective to take on this. This sort of behavior you are describing locks you further and further into the role you are in right now, reducing the rate of which you grow and learn. It sets up by dynamic where the company is incentivized to keep you there.

Another possibility is that you make yourself entirely removable or even just solve the problem so well that it no longer needs headcount. Instead of seeing people reaching out to you as satisfying a "I feel needed" emotion, you can see the need to have been reached out to as a tax that reduces the value you create.

Businesses really like developers who reduce replacement costs, solve their problems, and enable others. They tend to put them on increasingly valuable and interesting problems.

[pydry]

I've worked with the kind of developers who try to gatekeep their knowledge and the systems they work with. I find that a few of the following conditions tend to hold:

* They're not very good developers and not very smart and probably somewhat cognizant of that.

* They're afraid of interviewing.

* They're working in smaller markets (e.g. a town which has maybe just one or two companies that hire developers).

* They're spending right up against their income or beyond it and are afraid of losing their job.

If they hit all of these checkboxes then I reckon this behavior is almost guaranteed and getting potentially "redundancy inducing information" out of them will be like pulling teeth. They'll be busy a lot. Far too busy to talk to you. Their docs likely won't be nonexistent (too obvious), but they will probably be deliberately obtuse.

They're primarily concerned not with learning but with not losing their primary source of income and their time horizon shortens, much like it does for those stuck in a behavioral poverty trap https://www.sciencedirect.com/science/article/abs/pii/S03043...

Yes, this sort of behavior locks you further and further into the role you are in and is possibly self defeating, but it's entirely natural and fairly common.

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

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

[aflag]

Fair point, but I really doubt that is really a key component, specially given how fruitfull the developer market is. Very few people stays in the same company for more than 3-4 years in my experience. So, if you're just going to stay a couple years, you probably don't care about your replacement value.

I'd say that, in general, people don't like writing docs or answering to people. But if someone asks you a question, it'd be very hard to decline to answer, whereas writing documentation takes effort and initiative (and it won't prevent people from asking things, because most people don't like reading docs). Unless there's someone pressing for people to do it, they simply won't. Both because they don't care about doing it and also because the activity is not valued anyway (ask any project owner if they'd rather have great documentation or one more feature).

Also, the value of documentation is questionable in the simple software using standard components as most of us do. I'd be interested in seeing a study to know whether good software docs really improve productivity or reduce the number of bugs.

[pydry]

You're right - I think a lot of people don't care.

However even if you take out the replaceability I still think that there's a relatively limited upside.

Thus you're left with conscience or a sense of professional pride as motivators to write docs.

[aflag]

Yeah, there are no incentives. No one will praise you for writing them, they will probably not be well maintained and other people will make changes and not update them. People will still ask you privately instead of reading the docs and will get annoyed if you tell them to read the docs. You yourself will likely not really refer to them anyway, as you probably already have them memorized for the 3 year period when they are relevant to you.

[thu2111]

Isn't stackoverflow a rather good demonstration of the point? People like answering questions so much they'll do it for free. There is no SO of documentation.

[afarrell]

> whereas the dopamine hit you get

But have you ever had a salesperson at the pub tell you about how much easier it is to close deals by pointing to the API integration tutorial you've written?

Hands down, absolutely the proudest accomplishment of my career.