This is because deliberate knowledge sharing is so ad-hoc and inconsistent. How often do new hires have to turn to someone to figure out how to get the project to build locally as the instructions suck? Quite often.
This is because deliberate knowledge sharing is so ad-hoc and inconsistent. How often do new hires have to turn to someone to figure out how to get the project to build locally as the instructions suck? Quite often.
Ostensibly Google/Amazon put a lot of thought and work into formalizing institutional practice and knowledge, and it likely helps that most competent engineers are gunning for a long-term role at those kinds of firms, but I've yet to see anything resembling such where I've worked.
Until then, I'd rather have things decentralized in their appropriate Github/Gitlab repository with issues and a wiki. At least this way you have all functional blocks of knowledge absolutely in one place since you can get code history, closed issues, and the wiki history in one place. I'd even go a step further and have design/UI as a directory in the repo.
ETA: Closest I seem to be able to get is this jira ticket: https://jira.atlassian.com/browse/CONFSERVER-27798
Onboarding docs need to be iterative. They need 'user studies' with some of the new employees. If I go through the onboarding docs with a new employee, and they get stuck, either I'm the one who knows how to fix it or I know the person who does, so we can get it fixed. Once that becomes opaque the docs are more of a sick joke than anything.
Confluence docs tend to be written as the result of timed events, for each project or sprint or meeting or whatever, rather than organized by topic. And most are write-only and never looked at again.
What a Confluence (or any documentation) repository really needs is continuous refactoring, to be organized by functionality rather than time implemented. Just like code, if you never do that, what you get is documentation debt and a big ball of documud.
If something is worth remembering, someone will take an action.
The other think I like it for is lists of 'learning' links Our team has a nice page with suggested books or lectures or tutorials that they think others will find useful.
Everything else is stale within a week or so. If I need to document something it goes into a Readme which can also go stale but is still a bit more in your face.
I've also seen what someone points out below - the engineers who think Confluence documentation counts as task completion.
> "Did you figure out how to do X?"
> "Yes, here is a confluence page."
> "Did you install it? Did you run it? Did you validate the results?"
> "... here is a confluence page"
It’s very weird how adverse people are to spontaneous phone calls. Especially the younger generation. Everything has to be scheduled and confirmed back and forth.
I understand that an unexpected phone call can disturb someone, but so can an unexpected tap on the shoulder.
I'd rather use e-mail or some chat system when remote and working on something else until I get an answer, unless of course, something is on fire.