DEV Community

José Martins
José Martins

Posted on

Confluence is where information goes to die

If, like me, you've ever worked with Atlassian's tools, namely JIRA and Confluence, you probably had issues with the latter.

Of all the projects I've used it, I always saw the two same problems, that are what bother me the most:

  1. Structure/organization of information: I never know where to find what I'm looking for, and I never now where I should put something new.
  2. Outdated information: who hasn't run an 'How-to' that breaks something because it's outdated?

I know the tool is not the problem here - because it's one hell of a tool - but we end up always using it wrong, which makes me question what should change.

Have you ever had these struggles? What do you do to fight them, or to even eradicate them? Some other tool? A Confluence manager?

Please share your thoughts. :)

Top comments (16)

Collapse
 
bizzibody profile image
Ian bradbury

What you're describing sounds very familiar to me and after several similar scenarios - I've come to realise it's all down to implementation.

If the tool is not implemented with thought and amazing communication then I'm pretty sure no matter the tool you'll experience these issues.

In fact I had the same type of conversation today when discussing the service desk tool we've been provided.

Thought, planning, inclusion, communication - repeat.

Collapse
 
psnebc profile image
Patrick Schanen • Edited

I have tested Confluence. Many people use it for big projects. First for me it is to slow.

  • Now i use Emacs Orgmod - Git - Github.

Alternative

Collapse
 
miniharryc profile image
Harold Combs

I've used 'Wikis' since "WikiWiki" was an unknown term. It's not just Confluence, it's a human behavior problem.

This is a generic problem with any system with zero curation and bad search. Information is out there, but you've no idea if what you're looking at is valid.

First, accept that basically anything else is worse. I'll never use Sharepoint again willingly.

That being said, there are some things you can do with your Wiki operations that make things better:

  1. Define "owners" for given pages. This can be a person or (ideally) a team.
  2. Every so often, run a script to mark pages as out-of-date. Ask the owner (see item 1) to re-certify the information (cut them a bug in your bug tracker) and if they don't, move the content to hidden (deleted), and after a year, delete it. You can get it back, but this keeps people on their toes.
  3. Write or enable a system whereby people viewing the information can mark it as wrong or out-of-date. This should cut a bug to the owner (see item 1)

The above basically encourage people to keep pages up-to-date. You're fighting human behavior, not any particular problem with Wiki/Confluence.

Collapse
 
ben profile image
Ben Halpern

We try to have a certain awareness that we're allowed to delete things that start to rot with the understanding that if it was so important someone will bring it up again. I think this helps solve the overload and mess. It sort of takes an acknowledgement of our own fallibility ahead of time.

Collapse
 
pabloportugues profile image
José Martins

By that you mean that when you're wondering through Confluence you're always on the lookout for deprecated stuff?
And how do you manage the structure, like what goes where? Common problem is like having an "Engineering" space and everything tech related goes in there. The opposite is also true, where everything is a sub-sub-sub-page, and then search doesn't help. Ever had any of those problems?

Collapse
 
pabloportugues profile image
José Martins

From my experience of Google Docs I think you'd be trading problems.
Never used Dropbox Paper though. Biggest problem is that outside tools will always be a hard sell, living in Atlassian world (Bitbucket + JIRA + Confluence) it's really hard to convince business to pay more for an extra tool, when they're usually fine with Confluence, or at least I get the sense that tech people are the ones who struggle most with it.

Maybe adding cookies to the proposal would do the trick! :P

Collapse
 
xowap profile image
Rémy 🤖

Wikis are boring. To me the simplest way to deal with that kind of shit is simply:

  1. Write all your documentation in Markdown
  2. Store it in a git repo (even if you have to create a repo especially for that)
  3. Never change the master/develop branches directly
  4. Whenever someone makes a pull request, make sure to check that it also updates the doc
Collapse
 
kjocevicius profile image
Karolis Jocevičius

Haha, toootally know what you're talking about :D

As a developer, I am a huge proponent of using README.md files inside the project, instead. Mostly because those are much more likely to be updated or read, when needed. At least for the project related stuff, this works great so far.
We just put README.md files at project roots and describe development setup, deployment procedure, coding guidelines (if needed), etc.

Another thing is bussiness/company related information and wiki's/how-to's, that change rarely. I guess it's ok to keep those in confluence.

Collapse
 
subbramanil profile image
Subbu Lakshmanan • Edited

So True. As you said, tools can only do so much. It's up to us to have better practices around them.

We are also using the Atlassian suite of products. They have recently improved a lot in their search functionality that helps to search faster. We also organized the documentation as the screenshot. This combined with search helps us to find items faster.

Confluence organization

For obsolete pages, we either mark them as 'obsolete' in the title or bury them deep in one of the Confluence 'spaces'.

Collapse
 
kostjapalovic profile image
Kostja Appliku.com

Confluence spaces is one and the main thing that makes all pages lost in this app. I couldn't simple recall where was that article in which space in which subpage.

After some time we understood we spend couple hours a week!!!! just organizing confluence.

Collapse
 
mgaruccio profile image
mgaruccio

Like you said the tool isn't really the problem here, the problem is the process around the tool. It's a good idea to sit down before you even start adding content and set categories and a rules-based process for what goes where. That way when your adding content you just move through a flowchart to determine location. It's also a good idea to have someone responsible for each entry, they don't necessarily need to be the only one updating it but they should at least know when changes are being made and it's their job to update when the content is no longer up to date.

Collapse
 
pabloportugues profile image
José Martins

I have to agree that with the old search any results just didn't make any sense. I always have a hard time remembering what should search for (thinking about keywords) and sometimes they're just near matches, which completely bunks the results.
I've found that with the new search (left bar that came with overhaul that they've been doing recently), it actually works as I'd expect it to. I'm guessing they updated the search algorithm.