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. :)

Discussion (18)

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 on

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 Author

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
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
pabloportugues profile image
José Martins Author

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
subbramanil profile image
Subbu Lakshmanan • Edited on

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

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 Author

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.

Collapse
kodierkroete profile image
Steffen Frosch

I do know the pain. Maybe if you move the documentation out of a third party application it could help.

Move it to the codebase, Like in a folder containing markdown or rest files. Adjust your definition of done. Changed behavior? The change only gets merged if the corresponding doc was updated or created. You could generate static HTML files from there or even import it in a CMS/Wiki/Anything.

Unfortunately there is no silver bullet to this. Just plain discipline.

Collapse
pabloportugues profile image
José Martins Author • Edited on

Confluence is the third-party! :D

I find that the README.md of every project is one the most important things. We usually only have setup there, but you always know where it is. Maybe having a wiki in each project repo... not that you could put everything there, but what was project related, everything else would just add info and link to there.

Problem with repo for wiki is that not all involved will go through the effort of writing markdown and using a VCS. Search and organisation would still be a problem, unless you added something on top of it that added at least search. Biggest point here for me is version control and the ability to do PR's for wiki, that would be a major plus!

Collapse
kostjapalovic profile image
Kostja

We've used Confluence for some time. With one of our clients we've used it extensively. And it help to solve a lot of problems, due to bad PM skills of the other side.

Then – we stopped paying that much attention to Confluence and everything became lost in sub-sub pages. Search didn't help at all.

After some time we understood that gitlab issues were better place to document everything in non-code environment.

After some time we understood that information is either important only NOW and we use gitlab issues, or it is related to code and engineers put it into .md files in app repo.

And there is another type of documentation, that lives in DropBox folders in .docx format, that is provided to client: usage guides and all that stuff.

Wiki in gitlab also doesn't work for us. It has same problems as everything else including Confluence.

Thinking of having repo for that and sphinx doc generator.

For some reason any kind of wikis don't stick.

Collapse
tonygraycanada profile image
Tony Gray

I used to think the problem was being unable to bind documentation to code. I thought Sandcastle was the answer, but building and associating the output with the code it came from was such agony that it all fell apart. We still use wikis, but my organization changes systems every 2.8 years and our accumulated wisdom is destroyed.