[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

[phaemon]

Would like to know this too.