[MattGaiser]

> Together, these effects may make it harder for employees to acquire and share new information across the network.

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.

[imbnwa]

Said this somewhere else recently, but I've never seen a Confluence that wasn't a disaster, magnified by the modern rate of turnover.

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.

[vikingerik]

Confluence is documentation theater. For most Confluence usage I've ever seen, the author's real purpose is mostly to signal that documentation has been written, and the experience of whoever might be using it later is a distant second.

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.

[specialist]

Add TTLs to all artifacts. Just like leasing IP addresses, certs, cache data.

If something is worth remembering, someone will take an action.

[nineplay]

I like confluence as a _temporary_ discussion space. Put up some mockups, put up some sequence diagrams, suggest external components and get feedback. It doesn't entirely eliminate design meetings, but it can serve as a overview so people have already thought about the design before a zoom meeting on it. A virtual whiteboard maybe.

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"

[hinkley]

There are too many degrees of separation in Amazon and I suspect Google's situation as well.

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.

[VectorLock]

I've spent a lot of time thinking about how to unsuck Confluence but haven't come on anything really great. It doesn't help the WYSIWYG in-browser editor isn't great, and its document model/API doesn't exactly lend itself to getting documents in/out of it from other systems like Markdown, etc.

[imbnwa]

IIRC Confluence defines its own dialect of Markdown as well, but I don't think the issue is the tech so much as enforcing some minimum discipline in encoding knowledge formally in a central, organized repository. That takes building a culture which in turn takes investment from management to acquire as far as I can tell.

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.

[hinkley]

There's some way to quote a markdown document stored in Bitbucket in a Confluence page. That's proved to be less of a pain than dealing with Confluence.

[VectorLock]

Confluence has a lot of ways to 'embed' other documents but they look like junk and aren't searchable.

[imbnwa]

Did not know that, my current shop is all-in on Atlassian so I'll have to check that out

[hinkley]

Looks like it's not out of the box, might be why you hadn't heard of it. Having trouble finding the name of the plugin.

ETA: Closest I seem to be able to get is this jira ticket: https://jira.atlassian.com/browse/CONFSERVER-27798

[iso1631]

Presumably just once, as the new hire updates the instructions

[tppiotrowski]

Yup. It's a living document and the new hire can update it in a way that makes sense to them and in turn to future new hires. All manager should encourage this from day 1. Be the change you seek.

[dcolkitt]

So… just call the colleague who knows on the phone? How is this any different than walking over to their desk and asking?

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.

[commandlinefan]

Voice calls combine the worst of real-time interactions (no chance to review what you're about to say for possible misinterpretation) with the worst of long-distance interactions (can't read body language). I literally can't for the life of me think of a worse way to interact with a human being than over the phone.

[ghaff]

There are very few people I will call out of the blue these days but there are certainly things that are much more easily resolved with a 15 minute phone call than going back and forth on chat or email over the course of an hour.

[guenthert]

When you walk over, you at least have the opportunity to observe whether the person you're about to bug is deep in the flow, cleaning up his desk or chatting with co-workers.

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.

[VectorLock]

Lots of people seem to have found a lot of utility in asynchronous communication and mitigating time vampires.

[908B64B197]

What I've seen some people do is create a Clubhouse like audio chat room. If they are in it, it means you can feel free to interrupt.