Confluence is where information goes to die

Byte My Bits on October 25, 2017

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... [Read Full]
markdown guide
 

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.

 

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

 

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.

 

I don't think it is the overload mess that creates the issue.

  • Bad search engine that can not find relevant stuff, poorly indexed and poorly executed.
  • Everything is a string - keywords, indexes and so forth, makes it slow
  • Too much irrelevant stuff.
  • Can not do phonetic search
  • It does not handle "near match", like we have a norwegian word "tester" that can also be written "testar"

Atlassian's products is relics. Only reason it is so widely used, is in my oppinion that it was the "de facto" standard and best tool on the market for years.
Now we have out-grown its usage, but sadly a lot of competetor's, like Github's Wiki, is just implementing a lightweight copy of Confluence instead of creating their own.
And let us not forget the main factor: Money. It will cost lots of money for these companies to find another documentation tool. So sadly, we are stuck with Atlassian's Confluence for years to come...

 

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.

 

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?

 

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.

 

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'.

 

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.

 

Sounds very familiar.

In experience, static documentation dies very fast, and we can not trust it for reference. We should be very careful on what to put in there. Projects that I have been on that works, it is only secure information that is in confluence, and only referenced from README

Documentation should be generated as far as possible since it just take too much resources to keep the static documentation updated - and sadly, nobody is willing to pay for it, and developer's can't estimate it in the tasks.

 

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.

 

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.

 

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.

 

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!

 

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.

 

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
 

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.

 

There's Dropbox paper and Google docs. Both are more searchable than confluence.

 

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

code of conduct - report abuse