7 ms·

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

roflyear 4y ago
Yeah, I push back when people say "can you document that API you wrote in 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.
Macha 4y ago
I'd take confluence over google docs because of how bad Google Docs' search is surprisingly
- l2silver 4y ago
  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.
  - Macha 4y ago
    They have no content excerpts in search results, so it doesn't provide any help for finding which result is the one you want. 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.
- matwood 4y ago
  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.
  - SgtBastard 4y ago
    Confluence’s search is so bad, it might as well be a Write Once, Read Never tool.
    - DocTomoe 4y ago
      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.
- triceratops 4y ago
  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.
- radicality 4y ago
  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). link: https://cloudsearch.google.com https://cloudsearch.google.com
PragmaticPulp 4y ago
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.
- triceratops 4y ago
  If using the lowest friction or default path in a tool leads to bad outcomes, that's a problem with the tool. Not the user.
  - PragmaticPulp 4y ago
    You create the lowest friction/default path according to your company's needs. 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.
    - triceratops 4y ago
      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.
      - DocTomoe 4y ago
EFreethought 4y ago
> The only use case for Confluence is when you want to hide information, but credibly claim that it's documented. That describes Sharepoint more than Confluence.
- triceratops 4y ago
  Sharepoint is what you settle for when you can't convince your company to spring for Confluence.
  - bornfreddy 4y ago
    Sharepoint is what you settle for when you hate the company, coworkers and yourself.
cmdrriker 4y ago
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.
- origin_path 4y ago
  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.
  - beachy 4y ago
    > 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).
fsociety 4y ago
Ha I hear this a lot but the alternatives I have seen used are frankly just as terrible. I much prefer Confluence to a hidden web of Google docs.
- edgyquant 4y ago
  For my team we’ve switched to using GitHub markdown files with flowcharts: located within the folder containing the subsystem it describes.
- civilized 4y ago
  Google Drive, the ultimate information black hole. Anything that gets sufficiently close will be sucked in and never seen again.
- mnd999 4y ago
  Confluence is garbage
SAI_Peregrinus 4y ago
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. [1] https://github.com/kovetskiy/mark https://github.com/kovetskiy/mark
- triceratops 4y ago
  So simple an idea, it makes you wonder why it's not already a core feature in Confluence.
  - dosethree 4y ago
    Bitbucket wikis basically do this.
balaji1 4y ago
Did I miss it or does the article specify what tools Tremendous uses for their documentation?
schnitzelstoat 4y ago
Yeah, the search function in my company's confluence is abysmal. 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.
arendtio 4y ago
So which tool do you like?

roflyear 4y ago

Yeah, I push back when people say "can you document that API you wrote in 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.

Macha 4y ago

I'd take confluence over google docs because of how bad Google Docs' search is surprisingly

l2silver 4y ago
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.
- Macha 4y ago
  They have no content excerpts in search results, so it doesn't provide any help for finding which result is the one you want. 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.
matwood 4y ago
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.
- SgtBastard 4y ago
  Confluence’s search is so bad, it might as well be a Write Once, Read Never tool.
  - DocTomoe 4y ago
    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.
triceratops 4y ago
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.
radicality 4y ago
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). link: https://cloudsearch.google.com https://cloudsearch.google.com

PragmaticPulp 4y ago

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.

triceratops 4y ago
If using the lowest friction or default path in a tool leads to bad outcomes, that's a problem with the tool. Not the user.
- PragmaticPulp 4y ago
  You create the lowest friction/default path according to your company's needs. 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.
  - triceratops 4y ago
    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.
    - DocTomoe 4y ago

EFreethought 4y ago

> The only use case for Confluence is when you want to hide information, but credibly claim that it's documented. That describes Sharepoint more than Confluence.

triceratops 4y ago
Sharepoint is what you settle for when you can't convince your company to spring for Confluence.
- bornfreddy 4y ago
  Sharepoint is what you settle for when you hate the company, coworkers and yourself.

cmdrriker 4y ago

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.

origin_path 4y ago
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.
- beachy 4y ago
  > 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).

fsociety 4y ago

Ha I hear this a lot but the alternatives I have seen used are frankly just as terrible. I much prefer Confluence to a hidden web of Google docs.

edgyquant 4y ago
For my team we’ve switched to using GitHub markdown files with flowcharts: located within the folder containing the subsystem it describes.
civilized 4y ago
Google Drive, the ultimate information black hole. Anything that gets sufficiently close will be sucked in and never seen again.
mnd999 4y ago
Confluence is garbage

SAI_Peregrinus 4y ago

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. [1] https://github.com/kovetskiy/mark https://github.com/kovetskiy/mark

triceratops 4y ago
So simple an idea, it makes you wonder why it's not already a core feature in Confluence.
- dosethree 4y ago
  Bitbucket wikis basically do this.

balaji1 4y ago

Did I miss it or does the article specify what tools Tremendous uses for their documentation?

schnitzelstoat 4y ago

Yeah, the search function in my company's confluence is abysmal. 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.

arendtio 4y ago

So which tool do you like?