Ask HN: What's the best way to manage institutional knowledge in tech companies? | Hacker News Reader

Ask HN: What's the best way to manage institutional knowledge in tech companies?

3 pointsanujvaishnav5 comments

While Jira helps document discussions on issues and features long term, information on old obscure bugs, debugging processes, admin, customer relationships, and special tools/processes tend to be left undocumented (probably buried in email, slack or in-person meetings). This issue is often worse for support and other business teams.

What are some good practices to avoid this? What can help reduce friction in documenting this institutional knowledge? How can we make institutional knowledge more accessible within the company?

View on HN

1. Slow it all down. Jeff Bezos may not be a good person, but he understands how to run a business. If he calls himself, "Chief Slowdown Officer", then maybe it's good for other organizations to think things through before doing them.

2. Reduce churn, both in employer turnover and in re-organizations.

3. Teams just need to talk to each other. It doesn't have to be everyone-to-everyone all the time because that's a function of quadratic order, but people should have a chance to ask each other questions.

4. Reduce scope.

My suggestions are mostly about avoiding the situation you're in. Legacy issues like yours are tough to tackle. The one obvious choice is a code freeze, then rewrite.

I found well written and maintained readme files to be useful. That and redundancy in terms of people who know the code base.

The best readme files write in english what the mode does, a sort of heat-map of the code ( often some parts are more used then others ) and pitfalls.

I’m also a big fan of short and succinct comments in appropriate places. I once broke production because I saw a private key being written to kafka. It felt odd so I removed that. Turns out something was reading that private key. There’s now a comment saying “When checkin data, double check this other module”

But the best thing is to have shared knowledge. I don’t think it’s useful or practical for regular engineers to know everything but the tech leads should be able to provide guidance across the larger cod base.

I've thought for a long time that having an org historian/librarian would make sense. Someone whose job is just to interview people in the org about what they are working on, what sorts of things they know about, any special things that person feels only the may know about ,etc. Then compiling that into something that is searchable but also acting as a resource to the org for "I know someone here has solved a problem like mine before but I do not have a way to find out who".

Most places I've worked have had people who are longer tenured fill this role unofficially but I think there would be value in having it be an official role.

My anecdotal .2¢ from a developer perspective:

Jira is difficult to search and gives teams too much flexibility on organization. The latter makes it difficult when going from one team to the other.

Someone needs to champion documenting. Especially getting knowledge out of slack and similar tools which also have terrible search. Whatever the tool IMO team members need to feel empowered to contribute and edit.

In my teams- Microsoft Word/Excel/POwerPoint is banned. It must go on Confluence or Gitlab Wiki.

Notion (https://www.notion.so/) is a very popular paid tool for documentation and knowledge sharing. We have used Notion for documenting every process in a startup, and it worked really well.

Reply on news.ycombinator.com