Regardless, Is this a solved problem? What are the common failure modes of knowledge management systems like Confluence in large organizations, and what are some strategies or alternative tools that have successfully combated this? There’s no way that no one has solved this.
Search is the real value though. I never remember where a certain doc is stored. But if I can remember who wrote it or some snippet from it, I can find it. They link to each other well. Another pointer is from Slack; maybe it needs this kind of combo to work well together?
Your experience was the motivation for StackOverflow.
It's goal was to be better at surfacing information than forums and the Usenet.
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.
Now that said, I have yet to actually use a platform with a good search functionality too. If stuff was easier to find, I strongly suspect that documentation would be better maintained, (provided that there is a cultural value around it)
One solution to this is to write structured and testable documentation. Easier said than done, but if your docs get regularly integration/e2e tested against reality, they stand a much better shot at staying up to date. I always recommend moving the docs as close to the development work as possible - ie docs get checked into git alongside the code and make sure tests fail if anything changes.
I don’t want comments saying “adding 1 to X” but I DO want comments that tell me WHY we are “adding 1 to X”.
I’ve been told by a few developers over my career that “comments are a code smell”. I believe this is well intentioned but ultimately harmful advice.
I’ve written mini-blog posts in comments before to explain a complex system or an odd bit of code that is the result of a massive bug in production that I want to document and explain the reasoning behind 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
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-...
What is everyone's responsibility is no one's responsibility.
I've been at places with good documentation and at places with bad documentation. The places with good documentation have someone (or maybe a team) with responsibility for documenation. It could be a developer, it's better IMHO if it's a technical writer. They don't need to write all the docs, but they're in charge of editing and organization, and checking to make sure docs are current and assigning people to update them/provide information so they can be updated.
If your org lacks a documentarian, you'll get chaos documentation, which tends towards poor documentation; this is a choice. If your org has a documentarian, but they don't have time to do it, your org has chosen other priorities over documentation. If your org doesn't include documentation in evaluations, it's not an org priority, and that's a choice, too. I've been at places with a self-appointed documentarian, and that can work too, as long as they can cajole others into doing the tasks that they assign.
On teams that I run there are many things that are everyone's responsibility. Here are some of them:
- Everyone is responsible for showing up on time
- Everyone is responsible for being respectful
- Everyone is responsible for maintaining documentation
I would not say that saying that everyone is responsible for something automatically makes it that no one will do it. Managers and peers need to work on supporting these responsibilities.
I agree that documentarians do pick up a lot of the slack, and one or more are needed to make documentation useful. However, it is not solely their responsibility to maintain documentation. Everyone is a domain expert in some area, and they need to own the relevant documentation.
These two are usually an HR issue, the third isn’t. So unless your org makes lack of managing documentation an HR issue like the other two I don’t see the relevance.
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
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.
yamatokaneko•12h ago
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.
NanaAmun•12h ago
shadag•11h ago
shadag•11h ago