> Confluence
There's your problem. The only use case for Confluence is when you want to hide information, but credibly claim that it's documented.
There's your problem. The only use case for Confluence is when you want to hide information, but credibly claim that it's documented.
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.
There isn't a universal note taking application that comes pre-organized for your team's use case. You have to put some work into any tool you use.
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.
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.
I personally have never seen it work, but of course I've also only seen a handful of data points.
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.
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.
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).
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.
A ticket represents a process (otherwise it has no added value over git commit message) and thus creates much more work than a couple of seconds.
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.
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.
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.
It was a directory of files - I think plain text with a few wiki shortcuts, but might have been some sort of early Markdown.
The editing form was basically a text area on top of mercurial.
Similarly things like the edit log were basically dumping the mercurial output into html.
No clue how long it lasted, but it was still in regular use when I left in 2012.
Wrote the whole thing in a few afternoons.
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.
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.
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.
It also weights titles incredibly heavy, which combined with the previous part led to me not even noticing it searched the document body for years.
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.
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.
There have been times I know a page exists and I even know the title/content of the page and yet still I am unable to find it via the search.
That describes Sharepoint more than Confluence.
It is such a stupid idea that it makes me question leadership.
Some things are good to document there, but generally, if you're documenting code, you should do it in the code.