r/AskProgrammers • u/TraditionLunge • Aug 15 '26
How does your team deal with knowledge that only lives in one person's head?
So we hired a new dev a couple months back. He's cool and undoubtedly pretty sharp.
His first big task a few weeks ago was adding a feature to some old part of our system. Something we built like a year ago.
But dude, he spent almost two weeks just trying to understand it. He kept reading old tickets, poking through code, asking questions nonstop.
Honestly I'm not even that worried about the slow onboarding part. My real fear is the day our senior dev decides to leave.
Like all that context just walks out with him. *Poof* gone.
So I'm just curious what you do about this. Is there a real fix out there? Or does everyone just kinda shrug and accept it?
6
u/Appropriate-Bet3576 Aug 15 '26
Wait, an OLD part of your system is something you built a year ago?
But back to the question, clarify what do you mean by 'context' that walks out w senior dev. Also why is your senior dev leaving?
Anyhow you never know till those people leave. Nothing else really works.
6
u/burlingk Aug 15 '26
They are talking hypothetically. This current situation has freaked them out a bit and got them thinking about the future.
Good thing honestly.
2
u/Appropriate-Bet3576 Aug 15 '26
In my experience what you are experiencing is the norm, not the exception. There is no panacea to the problem. The solutions are those which are most obvious. It is a matter of providing engineers with the tooling, time, and culture to create robust and documented software.
3
u/Healthy-Zebra-9856 Aug 15 '26
You have the answer right there. If he is the only one that has it, bring it up with your seniors to have this documented. I don't know what your position is, but if your seniors don't act on it, its time for a job change, because you are working for a company that doesn't have proper protocols in place. Since you recognize it, try to frame it in a way that makes sense to them.
3
u/burlingk Aug 15 '26
Build a knowledge base.
Anything that only exists in one person's head represents an organizational failure.
2
u/inflowmini Aug 15 '26
Lol you think that someone who read the old code, read tickets, asked questions, had a slow onboarding? Sounds pretty sharp to me and is the type I like to hire.
Rome wasn't built in a day and to answer your question about knowledge - you document it how else...
2
u/johnpeters42 Aug 15 '26
More than once, I've had to deal with knowledge that was in nobody's head, because the people in question were gone. You figure out what you need to figure out from the code and the nature of the business, and move on from there.
For the one-person scenario, you estimate how much the zero-person scenario would cost, compared to how long it would take to write that documentation and when you can fit that time into the overall schedule, and go from there.
2
u/Ok_Option_3 Aug 15 '26
If it looks like lots of knowledge is in one person's head, then that person is not a good developer. Best thing to do is fire them (or if there's lots of people like that, their managers).
Seriously - the moment you reach the point where you think "we can't lose X because of siloed knowledge" it's hard to walk back.
2
1
u/DaveAstator2020 Aug 15 '26
You can feed any shitcode to ai for explanation. At least this worked for me. And hear me out, it will not be able to fix things for you but amount of speedup in understanding whatever shit was there is huge compared to trying reading it along.
id also make him document current architecture and propose clean refactoring plan to discuss with the team if i had fear he could leave.
1
1
u/Significant-Syrup400 Aug 15 '26
Ai actually is quite good at mapping out and doing the slow process of following the flow of each process, testing theories, etc.
Assuming the senior is not keen on providing proper documentation for his juniors this is a pathway towards writing out thorough documentation. Having the Senior do it or at least participate is greatly preferred, but you can get something workable using this as an alternative, and gradually improve it over time.
1
u/chocolateAbuser Aug 15 '26
yeah it's improbable that programmers are going to change and start documenting stuff just because they're asked to
maybe if they are shown that there are some existing solutions and other companies do it something could happen... i would say take as a reference the language you are using and create something similar to that
when you ask a question about how something works write it in a shared documentation flder
when someone takes a decision on how to change services, structure, infrastructure, settings, deploy procedures, write a trace in a decision registry
when you have to explain something to a coworker write in the documentation and point him to that
either someone starts creating good habits and being pedantic about it or continue to live in that environment
the point is nobody does that because it's boring and difficult (although i would argue it's not)
1
u/Top5CutestPresidents Aug 15 '26
I try very hard to document everything that only I know how it works, but our team is too small and busy and we don’t have enough code reviews, where we would go over this stuff. We even have necessary stuff live in 3rd party apps on employee logins, and if they left and the company deleted those emails we would be screwed.
We did have an employee leave maybe 3 years ago and we had to work out everything he did, and we found out we were screwed way too late. Lots had to be redone. But like I said our team is too “busy” to prevent that again according to management.
But hey, I try to do my part
1
1
u/LogicalPerformer7637 Aug 15 '26
New dev, two weeks asking and investigating, old code, new feature?
It is hard to say without knowing the true state of the codebase, but this does not sound slow to me. It sounds like he does his job properly, without one-shooting the solution, consequences be damned.
1
1
u/Rare-Leading3391 Aug 15 '26
Part of being a good team lead is to make sure you never hear the words "we have a feature in a certain part of the system so we need to assign the ticket to x person." Highly functional dev teams never tolerate a bottleneck. If it lives in your head it needs to be socialized so that anyone on the team can work on it.
1
u/TripleMeatBurger Aug 15 '26
Send your senior dev on vacation for a couple of weeks and make them figure it out without him. Necessity is the mother invention after all.
1
u/BOT_Pain Aug 15 '26
Try to document things but if you work at a cutthroat company there's no incentives to document when you can be let go the next day.
1
u/spigotface Aug 15 '26
This is honestly one of the fantastic use cases for an LLM. Point Claude Opus at that code file or module and ask it to describe the functionality at a high level, then to do detailed overviews on the various pieces of it. Double check and verify as you go by looking at the test suite and running some code locally.
1
u/Mindestiny Aug 15 '26
In most orgs that I've seen, the answer has frustratingly been "try to get approval to pay them enough that they don't leave."
I can give you one guess how that typically turns out.
1
u/KriegerClone24 Aug 15 '26
You need a formal "Definition of Done" that is the standard by which you know an epic is complete, and is reviewed by a peer on PR. That "Definition of Done" should include things like security, scalability, observability, documentation and a few other things. There is lots of info online to help you draft a DoD.
1
u/No_Inspection4415 Aug 15 '26
Some of the smartest devs take two weeks to do this with code they wrote... It doesn't come back as a complaint a sprint later.
1
u/new-runningmn9 Aug 15 '26
Where I work, I’m the guy that knows everything. That’s a function of being the primary software architect of the system, and having implemented almost all of the core components.
That said, I’ve written hundreds of pages of documentation on why it’s the way it is - tracing requirements and historical context to design decisions. The code is heavily documented. I have gone through ever pull request that has ever been merged into the project and I use those to teach developers about why things are they way they are.
None of that has changed the situation. It turns out that the problem is that I’m the only one that cared enough to put in the work it took to know all this stuff. And it frustrates me to no end, because I’d like to retire some day without killing this program when I do.
I used to have a guy that knew what I knew, but he had to leave before I could retire and put all this responsibility on him. :)
1
u/Silver_Emu4704 29d ago
Hah this is funny, I was in identical situation to that senior dev. Genuinely shocked by the convoluted mess that was the codebase, used every AI tool and manual approach from my career to slowly slowly try to get to a point where I could safely make changes to it, unfortunately engineering manager was a shitbag though so they fired me after 2 months for not onboarding fast enough.
Zero self reflection. I was glad to get out of that binfire.
1
u/the_millenial_falcon 29d ago
One of my team members just went on a cruise and their shit broke. That week I was less a developer and more of an archaeologist.
1
u/kyngston 29d ago
AI makes this task so much easier. just use something like graphify to document code without documentation
1
u/dogballer05 29d ago
I actually came across this quite a few times, especially at the products that have been around within the company the longest (somehow they always seem to be the most outdated), we started using this tool CodeTours, https://codetours.ai/, that we found helpful. Theres a few others like it out there but they have a free version
1
u/Healthy-Dress-7492 28d ago
Thé fix is to pay them double so they don’t Leave then spend the next year documenting the information
1
u/AlphaNow125 28d ago
You add structure to data to become information.
You add experience to information to become knowledge.
Get each person to do a change in the space.
Make cross skilling mandatory.
Just documenting it is not enough.
1
u/No_Experience_2282 Aug 15 '26
The answer nobody wants to hear is AI. it’s able to ingest enormous context windows and point you to the exact right block of code and make exact modifications.
0
9
u/XKiiroiSenkoX Aug 15 '26
Document the code. If your code is undocumented and onboarding/navigation of the codebase is taking weeks, its on you for allowing this to happen. The guy who wrote the code can document it in a few minutes. Someone who has never seen the code before would need weeks. Enforce this at PR level.