Is every company's internal wiki just broken by default?

I don’t think it’s about the tool. Whether it’s Confluence or Notion, if the company doesn’t value documentation, it’s never going to stick.

I don’t have a clear answer, but I think the future lies in automatic capture + AI search, not manual input + folder systems.

For us, once we started recording all meetings, the voice conversations became searchable. I'm looking forward to the same kind of AI-first approach for written docs too.

You can download everything and embed it with Google api and dump it in postgres with pgvector. Works pretty well for me for similar situation

For midsized corp it depends on if the company actually cares, i.e. their philosophy, which is horrid most of the time and doesn't even touch on wikis, and when it comes to larger corporations, it is broken whether anyone likes it or not, because the sheer amount of information becomes unnavigable and unorganizable really easily.

Recently worked at a large sized international corp. tbh I don't blame you, this was part of the reason I left for a smaller company. Best solution I found was to search by keywords and crawl thru results with GPT. Not exactly ideal but much better than navigating the insane hierarchy of pages littered with corporate buzzwords

Interesting. We argue that Confluence was the best tool we have and has some of the best search. People would rather write in GDocs, but ironically, the search has been much worse.

Is this a solved problem?

Your experience was the motivation for StackOverflow.

It's goal was to be better at surfacing information than forums and the Usenet.

The big issue, regardless of the platform, has been getting people to care about documentation. Those who are most qualified to write it, are usually the ones least likely to care about, because they don’t need it. I tried to buck this trend, as up-skilling others, in ways that didn’t require my constant time, seemed like a win. I tried to lead my example, but no one else ever joined in. I tried putting something together to formalize the process of reviews and got nothing but lazy rubber stamps, even from people who typically did excellent work. Getting people to care is the hardest part, in my experience. The bigger the organization, the worse this problems seems to get.

After seeing some people delete some big docs I wrote, which I think were still good, and changing documentation platforms so many times (usually to platforms with higher friction), my motivation to be a champion for good documentation has waned significantly. I still do write good readme files for my code, and end user docs for its use, but all the other little nice to have stuff I mostly just keep to myself in my own system. I’m sick of the changes, the friction, and people blindly deleting my work out of ignorance.

only one that i've seen that wasn't 100% borked was a doku wiki at the niche MSP I started at in IT.

literally every manager had "documentation accuracy" as a metric for their domain and they were generally good about things like "did you check the wiki?" when asked questions -- which usually led to a "okay, once you find it, add it"

every single company with confluence was a disaster of unreadable garbage. one place got so bad the ops / support had their own "secret server" of internal docs which were mostly links to text files

I'd say 2/3 of the time I find what I'm looking for on first page of search using Confluence, 2nd page is totally irrelevant. So I'd say it's not that it's broken, it's just that it isn't there and that tribal knowledge isn't written. So imo forcing tribal knowledge to be written documented is the issue. LLMs won't help here because a contractor or first line employee has conflicted incentives whether to document their tribal knowledge which loses them value

None of the companies I worked for have decent documentation. I'd say either one needs to read comments in code, or hire someone specifically for writing docs, like the more traditional companies.

Documentation needs to be maintained. Period. There are no shortcuts.

When people join your team, stress this point. In the onboarding, require them to make at least one change to the documentation during their first week. People tend to think that documentation is someone else's responsibility, and it just isn't so.

The main problem is not a lack of documentation, but being able to find it. Search is woeful in all the documentation systems I've used. The only thing that can save the day is proper linking of related articles.

By default, people tend to throw documentation into a hierarchy. While that works for many things, it creates a structure that ultimately makes it hard to find things. Most documentation is related to a few different areas or domains, and with a hierarchy, you can only put it into a single "folder."

Any time you add a piece of documentation, you should link to it from at least two different places. Spend a moment and think about the person who will look for the thing you just documented. Where are they likely to look for it? Link it there.

If you ever look for something like OP, and can not find it easily, but ultimately do find it, add links to it in the places you looked earlier.

Over time, if enough people do this, the documentation will get decent or even good.

It's a solved problem in the sense that there is a solution, but the solution is not automatic. It requires someone to manage the process and the people to keep the documentation in a good state.

I wrote an article about this some time ago: https://koliber.com/articles/engineering-documentation-best-...

I find wikis to always rot. In-code class/function/library documentation and --help for CLI tools are more likely to be updated when anything changes.

Common failure mode is people. Most processes eventually fail when people start to slack on the little things, then the big things. Every part of knowledge management is tedious from capturing things to keeping them organized and discoverable. For any large organizations, there are a ton of knowledge that will remain tribal despite best efforts.

This is why knowledge management is such a popular use for POCs involving LLMs, and ironically also why POCs don't progress into something more permanent

I dont think this is a Confluence or a wiki problem. It's a knowledge management problem.

Here's how it works for me:

1. Solve a problem

2. Make a note in confluence and in my personal notes.

6 months later, same problem. I know I wrote it down. What follows is an hour of frantic searching both in confluence and my local notes.

I'm the only one that can be blamed in this case. But:

- I gave it what I thought was a good title

- Decent set of keywords

- Slotted it in the appropriate category in the confluence tree

I'm experimenting with Amazon Bedrock - search combined with chatbots - but so far it hasn't been the panacea I was hoping for.