Confluence (and all of the similar products) can be used successfully, but you need the teams to agree on and enforce a logical document hierarchy. It’s not really difficult to organize a company wiki into teams, projects, and other logical divisions if you make it a priority.
The primary failure mode I see is when people just throw random documents into Confluence wherever convenient at time of writing and never go back to logically organize anything. One symptom of this is when key information is being recorded in a hundred different people’s “Personal Space”
Taking even half a day to organize the average Confluence makes a huge difference.
I disagree. The point of a tool is to reduce work.
Most teams and companies aren't special snowflakes that need individualized organizations, and document hierarchies. There can be such a thing as sensible defaults that you customize or tweak later (no idea if Confluence ships with that - I've only ever seen Confluence installations in their already-screwed-up state). At the same time, an inexperienced user staring at a fresh Confluence install isn't going to get the organization correct right off the bat.
If you have to put in work upfront before the tool is even halfway useful, it better be really damn good after that. Confluence is not.
Disclaimer: I am a consultant working for an Atlassian-centered consultancy. I do a lot of Confluence-based projects recently.
You would not believe how special some use-cases are, especially when you work with organisations that have highly regulated environments. I've seen anything from markdown files in a git repository being semiautomatically created in a Jenkins run to an organization having built essentially their own wiki software because nothing on the market fulfilled their need at the time (now 5 years later, they realise no-one uses that thing because it is just unintuitive). I have seen organisations that have no content oversight and some who had a whole department of "content czars", whose sole job it was to keep their documentation fresh and updated. I've seen organisations that had strict rules on approving each individual change, with complex approval workflows.
If you have never documented anything, Confluence may be overwhelming, but so will every tool that has "sensible defaults", because before too long, you will start hitting the envelope. Documentation software is not like a MacBook that you just buy and start using, you always need some level of customisation.
So, is Confluence damn good? No - there's a lot that could be improved. But from the mediocre solutions on the market today, it is one of the better choices.
Does it matter what tool you use to write documentation? Confluence gets a lot of sh*t because its in the grown-up camp of tools but I know people who've got problems even with nano.
It's incumbent upon all users or members of the team to use the common tool along with agreed upon standards. Otherwise even if you wrote documentation in your own hemoglobin, no one would touch it either.
Some manager prob chose _________ as the tool for ticketing, documentation, etc not because it was good at ______, or _______ but because it fulfilled their action plan to have something, anything in place so that if the universe goes supernova, well some stuff was written down.
In my journey it seems that nobody is willing to criticize Edward Teach for the lousy treasure map he left, but rather we make fun of those who're still looking for his stuff.
It does matter because the issue with wikis (not just confluence) is there's no approval or review workflow. Imagine trying to write a large program in which everyone could just commit at will, with no review process whatsoever, and where nobody had made any decisions about design up front. There'd be duplication, dead code, the organization would be crazy.
That's the average wiki. It's a commons and a tragic one. To make docs work you have to treat it more like a codebase: clear ownership, standards, review processes, approvals, up front design, refactoring efforts etc.
> To make docs work you have to treat it more like a codebase: clear ownership, standards, review processes, approvals, up front design, refactoring efforts etc.
Maybe true in large orgs.
But for smaller companies what I've seen is usually paralysis.
e.g. someone notes a problem (maybe just a typo) in the doc. Can they fix it within seconds? If instead they need to raise a ticket then most likely it ain't happening. They move on, and the next person experiences the same problem.
IMO the default should indeed be towards everyone committing at will. Yes that will result in the occasional snafu. Fix that when it happens. (obviously not good practice for the operating manual for a nuclear power plant - but for a <500 person Saas company it is).
Mandating a Jira ticket for simple typo fixes is overkill. But if you make it easy to create a PR directly on the documentation file, without leaving the tab, I don't see an issue. This is already a Github feature.
We did PR's on documentation files at my last place, it worked but it was more painful than getting reviews for code PR's. Tickets work because they can be reasoned about, shoved aside, brought back into the limelight, updated, other tickets can easily be related to them as more information is discovered, etc.
Overall the comments on this page fall into 2 camps, people who've tried it all and found what works is discipline and those who are still trying it all.
Disagree. A ticket should be created for any change, no matter how small. It takes seconds to write a title, body and hit submit. I've seen those small ad-hoc changes cause havoc because someone forgot to escape a single quote or didn't realize tabs were necessary and replaced them with spaces.
The default for Confluence is just that, everyone commits at will. There is no structure, tons of duplication, no standards when it comes to naming, formatting, audience, etc. I'm a huge fan of markdown/plain-text solutions, only because linters can be run that force you down one happy path. I don't believe Confluence has linters at all.
Yep, and that process also involves other people, to review/ approve the fix to the typo.
It then goes from being a few seconds of elapsed time and actual time (to just commit a fix to the typo) to taking hours, days or weeks of elapsed time and hours of actual time and forcing context switching on, and interrupting the workflow of, all of people involved.
The last thing I want is to raise the friction for writing down documentation.
It's hard enough to get technical minded people to contribute to a git (or style) based knowledge base.
Pick your poison I guess but I'm quite happy to have testers/BAs/directors/etc able to quickly jot down thoughts roughly than have it disappear into the ether.
> The last thing I want is to raise the friction for writing down documentation.
A better solution might be that anyone can write the documentation, and there is a maintainer who constantly refactors the wiki to keep it legible. Makes sure the information is not duplicated, adds hyperlinks to things, etc.
"Everyone's responsibility" sounds like an euphemism for "no one really cares". When people actually care about something, they hire an expert.
Why do you hire software developers, instead of making software development everyone's responsibility? Is that because most people suck at software development? Well, most people suck at writing documentation, too.
I mean. I guess? The difference between having it written down in Confluence and disappearing into the ether is academic though. Either way nobody will ever find the information again.
There are some really nice git-based wiki systems out there, and one is built into GitHub and GitLab. If you want that type of workflow for your wiki, it's easy to get.
Oh yeah it's not great either I agree. But the use case for Google Docs is somewhat different in my mind. It's good for collaboration and discussion, rather than a source of truth to describe "how things are right now". It's annoying if you can't find a particular document immediately but it's not the end of the world. Discussion on a Google Doc will happen for a few weeks or a quarter, then die down and the doc will seldom be looked at again. You might link to it from tricky parts of your codebase but it's not essential to a high-level understanding.
Confluence and other wiki systems are clearly meant for longer-lived documentation and canonical information. You should link from or attach your working documents (spreadsheets, slide decks etc) to your wiki documentation for people to discover why certain decisions were taken. But if the wiki's discoverability is poor or it's not well-maintained or regularly reviewed, it's basically useless.
Interesting. Not that long ago we moved everything out of Confluence into Google Drive because GD search worked. Confluence search was horrible to find docs I knew were there.
That's because no-one bothers to read the documentation linked in the search field.
Protip: Use wildcards extensively. Differently from Google, Confluence search considers keywords entered to be limited by word delimiters. so foo matches only foo, not barfoo or footer. Use them with some wildcards, foo, and the search results starts to make sense.
Do you mean searching within a document, or searching with google drive? I've found that google drive search is incredible, they've done a great job of indexing everything.
Not a fan of Google docs either, but I recently discovered CloudSearch which imo does a better job at searching Drive (and searches emails too, and few other places).
We use Mark[1] to automatically create Confluence pages from Markdown documents in our git repos. So we can have a review process for documentation changes, the documentation of the code can be in the repo with the code, and yet it can still be accessed without having to give permissions to view the code repo! Helpful with a proprietary monorepo.
The primary failure mode I see is when people just throw random documents into Confluence wherever convenient at time of writing and never go back to logically organize anything. One symptom of this is when key information is being recorded in a hundred different people’s “Personal Space”
Taking even half a day to organize the average Confluence makes a huge difference.