Ask HN: Is every company's internal wiki just broken by default? | Hacker News Reader

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

33 pointsNanaAmun47 comments

I just wasted half my morning digging through people's profiles trying to find something, only to randomly stumble on the real answer buried in a random comment under a half-related post. I feel like I spend hours each week sifting through Confluence, I know there's valuable stuff in there, but the search is impressively useless, and the people who actually know how anything works are either impossible to reach or long-gone contractors. Am I losing it, or is this just how it is everywhere? I'm at a F500 company, so nothing's changing here anytime soon, I’m thinking of jumping ship.

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.

View on HN

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.

Get people to be rewarded for it and they'll immediately care, I think? It's hard to blame people for not caring about something that has no impact on their performance reviews.

I was told by management they’d bake it into reviews to help drive adoption, but I don’t think they actually did.

Sounds like we work at the same place.

I fully agree with your analysis here, but I would also add that documentation getting out of date is also a huge problem. Out-of-date documentation can be worse than no documentation at all when it is actively wrong. With the pace at which many software projects change, it can take almost no time at all for documentation to get out of date. Even just business processes often change quickly enough that information on the wiki becomes misleading.

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)

Exactly, If I can’t find 90% of the docs, chances are most other people can’t either, therefore no ones maintaining them.

> Out-of-date documentation can be worse than no documentation

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.

Imo this just leads to out of date docs within the code it self. We have a no comment policy at the place I work for this reason.

What??? Like no code comments? That sounds insane to me.

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

You’re not wrong, it is insane.

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.

Huh, I’d be interested to sit down with someone like that and better understand their viewpoint. I wonder if it’s just comments that describe what the code is doing (“what” not “why”) that they have a problem with and are just throwing the baby out with the bath water.

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.

Documenting every piece of logic just because, I believe, is a code smell. However, look at Rust's documentation (or public crates, at varying levels), all the documentation is extracted from the code, with internal links and even external links between crates thanks to cargo doc (which I think is many times better than doxygen and what the Java and C# guys use, and let's not talk about the nonexistent alternative for JS/TS). Code examples in Rust docs can be made to reference the actual code in the crate, and the code block can be marked as "it compiles", "it doesn't compile", etc. And the compiler guarantees that's true. A block that doesn't compile is used as an example of incorrect code.

In the Unity game engine, they use docfx, and I heard from one developer that their system is done in a way that the code examples in the documentation import the actual code and the documentation fails a build if the code doesn't compile, similar to Rust.

This is what we did to improve our docs.

We built a tool that sets up screen recording links that, once the screen recording is complete, transcribes, AI processes and writes a page into our wiki with the video embedded into it.

The tool is pre-configured with standard meeting or documentation configurations so that the tool knows how to process each meeting or screen recording and transcript.

For instance, we'll have a documentation type called 'Infra/Terraform Notes' which once the screen recording is stopped generates a video, transcription, AI summary, keywords and writes it into the correct part of the wiki.

Further, we've introduced workflows so that you can chain multiple instances of this so that the AI can get smarter. For example; we've got a workflow for Requirements Docs where;

* we record the discussion with the client where they explain what they want

* that is transcribed and the tool knows to generate a Requirements Doc

* the developer adds a recording where he/she records screen recording explaining their approach to the problem

* that generates the developer design doc (using all the transcripts/ai output so far)

* the developer finishes the feature and records a screen recording explaining the outcome

* that generates a test plan for the QA person (using all the transcripts/ai output so far)

* QA person records a video showing all the testing that was done

* that generates release notes (using all the transcripts/ai output so far)

All this is compiled into automatically into a 'chapter' in our Features book in our wiki. The video and transcripts are added as attachments to the chapters.

It's nice to be able to go back through the whole history of a feature.

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

Totally agree, search is the real bottleneck. Linking from multiple places is such a simple but powerful habit, but again, I guess it comes down to people being lazy.

> People tend to think that documentation is someone else's responsibility, and it just isn't so.

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.

> What is everyone's responsibility is no one's responsibility.

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.

> - Everyone is responsible for showing up on time > - Everyone is responsible for being respectful

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.

All three are company and team culture issues. If you delegate all culture responsibility to HR you'll end up with a hot mess. Culture needs to be fostered on every level.

If you do not have backing from HR and senior management the issue will not change even if you tried.

Action without consequence causes these problems. If an employee is allowed to continually be late and rude it really does not matter in any way whatsoever if everyone shuns that employee culturally because the implicit statement is that that behaviour is acceptable but unwanted.

That is the exact situation you get into with lack of documentation, if a single employee never does correct documentation but there is no real repercussions it does not matter whether the “culture” is documentation, you have agreed by contract at that point documentation is not a requirement.

If you make it a matter of “Do the documentation correctly or we will be having talks to remove you” that clearly indicates it is not just lip service but is actually enforced culture.

Thinking the carrot will always work is part of the “documentation culture”. Make it a hard requirement or don’t do it at all.

Motivation, education, and enforcements are key.

While support from HR and senior management is helpful, I've found that most of the work happens at lower levels. In the end, it comes down to working directly with people to help them do documentation well. In engineering departments I've led, I did not need permission or enforcement to do good documentation from company execs or HR.

The "stick" that HR provides is a tool of last resort. At the same time, companies are different and what works in one might not work in another.

You don’t need permission but you need authority. Maybe you are US centric in a US state with weak employee protections so you can make those calls. In other jurisdictions it is a significant amount of paperwork and procedure to get rid of even an underperforming employee.

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.

Yeah, we’re trying that too, not going great haha. Recording everything sounds good tho, no clue how that would play with PCI DSS.

Yeah PCI DSS makes it virtually impossible. My company would take five years to adopt that

You're so right it's not about the tool it's about the culture and focus on excellence which translates to writing excellent internal docs for engineers to get things done. I'm not quite sure how recording everything would work. The real things we need are docs that are updated when there are issues with CI/CD after people read logs etc... recording things might work for more business or commercial teams but for us we just need people to keep everything up to date and well written.

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

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

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

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

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.

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.

Do you guys just dump all the dev/depl logs and docs into Confluence? Or is it more curated?

I'm not sure what you mean by dev/depl log, but there's architectural decision records in there. There's spike docs, which look into how long something would take - some have useful decision research, but they're generally not scrubbed out when done. Old stuff is swept into some "Archives" folder.

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?

Yeah, that makes sense, but that "if you remember who wrote it or a snippet" part is exactly the problem for me. If you’re not already in the loop, or new to the project, that context just isn’t there. Good search should work even when your memory doesn’t.

In godot engine we moved to the standard of every new feature requiring a godot engine proposal. It’s not much, but every little bit of documentation helps.

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

I get that, but scale’s the issue, there are over 10k engineers at my current company. I just don’t see how it scales when people are dumping tens of thousands of lines of logs into it daily. You can download everything and embed it using the Google API, then store it in Postgres with pgvector. At this scale, I’m not sure if it would hold up.

I totally agree with you. The solution mentioned above is useful but in my current company there is no way that can actually work long term for an individual engineer or my team.

That's an awesome solution - I'm going try that! Do people have other ways of doing that?

Yes! We just use MS Teams and keep a megathread of links honestly, it’s the best way we’ve found to manage it.

that's insane though. On a team scale this can somehow be managed by company has like 5,000 engineers on the main Teams channel. Surely there is a better way

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.

Yes. Use Glean. It's a very smart search across every knowledge base (Confluence, Slack, Google docs, Outlook etc)

Reply on news.ycombinator.com