Express this dismay to them, in a honest open conversation. Discover what holds them back. Be open, don't scold, maybe they reveal a problem in your attitude as well.
> Express this dismay to them, in a honest open conversation. Discover what holds them back.
Been there, done that.
The popular answer was that projects change too fast and he doesn not have time to maintain docs.
However, I firmly believe it all boils down to internal competition, and a refusal to give away to team members the knowledge they had to build up with their work.
Knowledge is power, and not disclosing how things work and why they worked is the key attain and preserve value within the team. You are a big shot if the things you do are hard and no one else can pull them off, and you achieve that by not giving away the information that allows others to easily do what you do.
There’s the occasional engineer who works this way, but I find it exceedingly rare.
A much more common pattern (though still not that common) is the mentality that they’re focused on high impact work, and documentation isn’t it. Selfish, maybe, but not outright malicious.
An even more common scenario (that covers the vast majority of cases in my experience) is an internal culture that values shipping above all else, and makes engineers feel harried. Even if documentation would reduce busywork and improve productivity long term, management is too focused on the short term challenges to see it.
As a team lead I would not except this kind of toxic gate keeper mentality. A single person with such a bus factor is a huge problem to a teams/projects (or God forbid departments) success. Discuss and frame it in terms of worries for business continuity with your line manager. If that does not click, consider it a red flag.
> The popular answer was that projects change too fast and he doesn not have time to maintain docs.
This is the problem I have clients will change their mind on core functionality from day to day with no understanding or consideration for how this constantly changing spec creates development hell.
I try talking to the client management but they also have no understanding of development. When I explain it to them and try to educate them they use their lack of understanding as an excuse to not try to understand.
Eventually they get the point but then just argue that its difficult to explain that to the customer and manage the customers expectations. I think yea no shit its difficult to explain to some one who doesn't understand but it is possible I just demonstrated that, now go do your job.
If they don't want to do their job they wont and no amount of polite talking to them will change their mind on that. If I eventually call them out on it, the hour I spent patiently explaining and reasoning with them is just ignored and I get called out for having a bad attitude.
At the end of the day the client management's only accountability is to the client so they just say yes to anything the client says, if that causes developer hell forever then thats the developers problem not theirs.
> The popular answer was that projects change too fast and he doesn not have time to maintain docs.
I sort of agree with this, but rather from the perspective that often the effort required to maintain documentation isn't in proportion to the payoff.
Naturally details differ among projects, but I find that the 20-80 rule applies to documentation, i.e. that 20% of the documentation provides 80% of the value. I find that focusing on stable architecture/properties of the system is a good approximation to the 'important' 20%.
If the system also has any especially tricky parts (e.g. a transaction coordinator) warrants documentation, but that also probably falls under the 'not subject to rapid change' 20%.
I'm assuming project internal documentation here. If you're documenting things for customers, then you'll want to document everything very thoroughly, but one would hope that people figure that out eventually when support tickets keep coming in...
As a programmer with ADHD, I'm actually the documenter more often than not: my memory is very volatile, and I don't want people to interrupt me, so I prevent it by giving them the information beforehand.
Or maybe they’re just not that smart or have mental bandwidth? I’m surprised more people don’t acknowledge that a lot of engineers in a lot of companies probably have at best average IQ if not lower.
Let's assume this was true. Are you saying colleagues with lower IQs shouldn't have been hired?
If so, I would be careful about coming to work thinking that many of my colleagues shouldn't have been hired. If that's actually the case, you're just in the wrong company and you should bail. Caveat: maybe you'll find your new colleagues lacking too, if you think that's widespread.
And if that's not the case, then you have to work with the colleagues that you have, regardless of how smart you think they are. And it's frustrating sometimes but only because you're thinking about the imaginary colleagues that you think you should have.
I think its more about trying, I think I have average or lower IQ but I try really hard to make up for it. I frequently see my colleagues say I don't know how to do that as if it excuses them from trying.
The same point applies though: if if you think a large percentage of your colleagues shouldn't have been hired, that's one thing... If not then you have to just make do with your actual coworkers. To the point of the root comment, it's no use deciding that you're done with your share of the work (you wrote the docs after all) and now it's up to others to do their part (why are they so lazy!). That's just fantasizing that you had different coworkers, and it leads neither to effectiveness nor to happiness.
I can’t speak to what my IQ is, or whether I learn faster than others, but I can, at the very least, say that I’ve put effort into everything I know.
So when something needs to be built as a Vue.js component, or we need new build scripts in our local environment, or a SQL query is slow, I learn what I need to and I do it.
Everyone else just throws up their hands and says “welp, I don’t know JavaScript” or “I don’t understand this old SQL”, as though they were born with the knowledge they have and will never gain any more than that.
Or maybe the next one will be much better. This actually happened to me. New company was a god-sent. Instead of most colleagues being the "throw arms up in the air at any slight complication and do nothing" I got wonderful co workers that both love their job and are good at it.
It is so great to finally have found other like minded people that you can just have an awesome discussion with on an equal enough level. Of course people still have differing opinions or knowledge about specific topics. We can have a heated discussion on what the best structure or naming is for something but you don't have to fight over whether naming is important in the first place and you don't constantly feel like you have to explain the basics on everything over and over, never getting anywhere.
In general, people who do most work tend to keep everyone around them hostage. People usually lack access to even basic stuff and nobody builds the organisation, usually.
The book The Unicorn Project shows how it is dysfunctional. Leaders tend to thrive doing nothing of value in such environments.
I really like this mindset. It's compassionate toward your co-workers and would make your entire team more effective. And best of all it's accepting reality and would make you happier too. Thanks for this.
The thing is, these kinds of organizational problems are almost NEVER about people not being "smart enough".
It's not uncommon to have utterly dysfunctional workplaces where the people are all very high in IQ (1), have premium academic credentials and stellar career trajectories. What matters, far more than raw intelligence, is people not behaving like assholes.
If people aren't reading and sharing beautifully prepared internal documentation, it's more likely to be about their perception of status about the author or lack of openness to new experience. A lot people are just incurious or are obsessed with their status. They tend to "punch downwards" and don't handle change well (or at all). This has little to do with IQ.
(1) We don't really know IQ do we? Unless it's measured we can only guess. When someone says that somebody has a high IQ, usually, it just means they perceive the person to be erudite or learned, acheivements, clothes, speech, vocabulary, appearance, credentials, titles-- all these things feed into that perception, but usually NEVER the score of a f-ing standard IQ test.
my reading of a lot is always more than 50%, which implies to me that more than half of the engineers at half of the companies have average IQ or lower - which seems unlikely.
on edit: unless of course we assume that development / engineering type careers attracted more people of average IQ or lower - but I think that will be a hard sell on HN.
> my reading of a lot is always more than 50%, which implies to me that more than half of the engineers at half of the companies have average IQ or lower - which seems unlikely.
That depends. It's unlikely that they have at most the average IQ of the general population.
But if we assume that engineers as a group are smarter than the general population, it follows immediately that over half of them are below average among engineers. If you mostly work with engineers, that will probably look like "below average".
> But if we assume that engineers as a group are smarter than the general population, it follows immediately that over half of them are below average among engineers.
Well, depends a bit on the shape of the distribution, because of mean vs median. But you are right enough for most reasonable distributions.
That's what the word "most" is for. A lot only means something like "large amount", with no hint at how large. It could be more than half, it could also be 1% because that's still a lot of people.
yeah if there's a context to a lot, as per the previous example of homicides, you can understand what a lot of homicides will be in relation to homicide rates in other places.
So if you don't really have an easy to understand context I don't know if 1% would be considered a lot.
Let's imagine the HN conversation:
a lot of people love the fruitcake they receive for Christmas!
I checked Santa's bureau of statistics - only 1% love fruitcake - is that what you call a lot?!?
So I guess I agree a lot doesn't have to be more than half, but when I don't have an easy to identify context I read a lot as being most. Surely my mistake, but one I feel is hard to guard against.
I guess the point is that if some people need to put in all effort just to deliver the required thing, while others can deliver the thing and have 20% time left, the latter people have much better time to do documentation.
So you say, why not plan for more time to do the task? Then the people who had 20% capacity for documentation etc. now have 40% capacity for that plus other things, and the same annoyance happens for the other things (e.g. unit testing, automation, etc.).
A good solution requires the company and the team to do the difficult thing and recognize and allow for the fact that different people spend different amounts of time on the same work.
And so they use that 20% to write documentation or do they move onto the next required thing? But here I think you’ve stumbled upon the root of the problem:
Documentation is the required thing.
Developers should slow down. Knocking out features is not the be all and end all.
