Ask HN: Good ways to capture institutional knowledge? • Hacker News Board

Re: Ask HN: Good ways to capture institutional knowledge?

#201

Post by yang10pan » Sun, Mar 01, 2020, 10:57 PM UTC

To provide a non-coding team perspective. Having an internal database of documents with search capability is critical for explicit knowledge , whether custom built or simply something like google drive. Having a formal process around adding to and updating this store of knowledge is also critical.

For tacit knowledge, the traditional form of transfer is simply interaction in the course of work. having a searchable archive of conversations is valuable. In most organisations, people are only able to search their own emails but not others. Chat is helpful for finding institutional knowledge around simple problems but not optimal for deeper and more thoughtful discussions that tackle larger issues. This is why I’m currently working on TribePulse, an internal discussion platform, designed to surface and capture institutional knowledge.

Re: Ask HN: Good ways to capture institutional knowledge?

#202

Post by Spooky23 » Sun, Mar 01, 2020, 11:15 PM UTC

fsloth wrote: post #119

AmericanChopper wrote: post #103

Earlier quoted context omitted.

I’m also a big markdown-in-source advocate. However it’s major shortcoming is that it’s not accessible enough for non-technical teams to maintain.

I don't know what the infatuation with markdown is beyond web publishing. Wysiwyg documents have been a solved problem for decades. Use what works on your platform. Markdown is fine until you realize you would like to have figures, images and tables. I don't want to spend my time over trite details of a text based markup when I could spend it actually productively. At that point it's way over easier to use a text pro…

This.

Markdown is great, but I’ve seen so much time wasted on Rube Goldberg solutions that would be trivially addressed by using less cool solutions like Word or GDocs.

Re: Ask HN: Good ways to capture institutional knowledge?

#203

Post by CharlesMerriam2 » Sun, Mar 01, 2020, 11:28 PM UTC

jupp0r wrote: post #174

CharlesMerriam2 wrote: post #169

The best is the enemy of good here. When I manage engineers, I insist on people having the old-fashion pen and paper notebooks: not scratch paper; not pads; not post-it notes. Simple 5 by 7 grids. During my weekly one-on-ones, I encourage people to make one or two positive changes: * jot down any odd term they run across so they can google 'strangeNewTerm slides' later and batch through them all * write a quick note…

Somewhat off topic: Not sure who you are managing, but for me being told how to take notes would be a huge red flag. Give your people some autonomy.

Everyone gets micromanaged for a moment until they move on. On your first day, someone micromanages showing you where the restrooms are and how the breakroom works. Then they never do it a second time.

In practice, you can revisit even a small point like taking notes as often as the other person finds experimenting with your advice makes her a better engineer.

Re: Ask HN: Good ways to capture institutional knowledge?

#204

Post by throwaway3563 » Mon, Mar 02, 2020, 12:46 AM UTC

jbn wrote: post #20

Alex3917 wrote: post #8

The easiest way is just to make sure product/business discussions happen over email rather than Slack. This way those discussions can be searchable and discoverable by anyone within the company at any point in the future. We make software for this (FWD:Everyone), but there are dozens of other similar solutions as well. That's the great thing about email, because the standards are open you'll be able to extract more v…

I never quite understood why companies don't just setup an NNTP server with newsgroups to capture conversations, rather than email (which is difficult to search IMHO).

They do, it’s just called Slack and Teams these days

Re: Ask HN: Good ways to capture institutional knowledge?

#205

Post by ulisesrmzroche » Mon, Mar 02, 2020, 3:04 AM UTC

HomeDeLaPot wrote: post #25

pyuser583 wrote: post #10

You’re not going to preserve their knowledge via a wiki. At best a wiki would be a snapshot in time. They’re irreplaceable knowledge is likely an understanding of how change happens within the company. The answer is by requiring close team effort. Pair programming for example. I’d one person leaves the organization, there should be “adjacent” employees who understand what they contributed.

That makes sense to me. I'm on a small team with several projects. Some people know more about some things than others, but we swap roles frequently. We explicitly try to share knowledge. We pair program and have daily standups. We also have a daily "tech time" where we quickly present the new things we've been working on. The end result is that everybody knows enough to pick up where somebody else left off. We can r…

Pairing is supposed to slow you down, that’s a good thing. As in, a quality solution takes more time than a shitty one.

What’s dumb is to do it Kent beck style, both people on the same keyboard at the same time. Cargo cult. I bet that’s how y’all doing it, judging by the open office comment.

Re: Ask HN: Good ways to capture institutional knowledge?

#206

Post by copperfitting1 » Mon, Mar 02, 2020, 7:27 AM UTC

tell me about more?

Re: Ask HN: Good ways to capture institutional knowledge?

#207

Post by AmericanChopper » Mon, Mar 02, 2020, 7:41 AM UTC

fsloth wrote: post #119

AmericanChopper wrote: post #103

Earlier quoted context omitted.

I’m also a big markdown-in-source advocate. However it’s major shortcoming is that it’s not accessible enough for non-technical teams to maintain.

I don't know what the infatuation with markdown is beyond web publishing. Wysiwyg documents have been a solved problem for decades. Use what works on your platform. Markdown is fine until you realize you would like to have figures, images and tables. I don't want to spend my time over trite details of a text based markup when I could spend it actually productively. At that point it's way over easier to use a text pro…

For certain use cases, markdown is arguably the best solution. For a team that uses an SCM like github (or any of the ones that natively render markdown), and that also has simple documentation needs, I can’t imagine a better solution. Markdown is fast to create, can be read rendered or not, can be included in your project repo and in pull requests. Images are easy in markdown, simple tables are easy in markdown (complicated tables very quickly move into don’t bother territory though). It uses the tools and workflow you already have to solve a problem very well.

If you need something more complicated than markdown can provide (depending on your renderer, that could something as trivial as line breaks inside the cells of a table), then it’s obviously not going work. But for any solution that’s great in one use case, there’ll be others where it’s completely impractical.

Re: Ask HN: Good ways to capture institutional knowledge?

#208

Post by m0zg » Mon, Mar 02, 2020, 8:38 AM UTC

MaxBarraclough wrote: post #186

AmericanChopper wrote: post #175

Earlier quoted context omitted.

> Why not use a wiki for the documentation of high-level decision-decisions? Because if you create different solutions to meet the publishing preferences of different groups inside the organisation, then I don’t think you’re meeting the goal of institutionalizing the knowledge. If a consumer wants to find some documentation, you don’t what their first step to be trying to find the system it’s stored in. Especially in…

> Because if you create different solutions to meet the publishing preferences of different groups inside the organisation, then I don’t think you’re meeting the goal of institutionalizing the knowledge. High-level project descriptions don't belong in code. It's a different beast, and doesn't belong in the repo alongside the implementation. Non-technical users probably shouldn't even have repo access. In-code comment…

> It's a different beast, and doesn't belong in the repo alongside the implementation.

That's just, like, your opinion, MaxBarraclough. If they aren't in the repo, they're never going to get updated, and as a result they will be outdated within 6 months on any project that's moving anywhere. I prioritize freshness of documentation against most other attributes. It does nobody any good to have documentation for the system as it was 2 years ago.

Re: Ask HN: Good ways to capture institutional knowledge?

#209

Post by raxxorrax » Mon, Mar 02, 2020, 12:50 PM UTC

Drdrdrq wrote: post #154

Techies4Trump wrote: post #91

Earlier quoted context omitted.

Solo people working on projects aren't too bad so long as they communicate the work they're doing and document it well. Some people just work better on their own. IMO, what's worse are "knowledge hoarders". Usually they've been in the company for a long time and they maintain their position by being as stingy as possible with their knowledge. You usually find these people in big orgs, and they can be quite toxic. The…

> Solo people working on projects aren't too bad so long as they communicate the work they're doing and document it well. Strongly disagree, been there, hurt like hell. Solo people on projects mean that other people can't give meaningful reviews (because they don't know the project that well, and because they have their own work), leading to 1. developer not getting good feedback and improving, 2. higher risk of them…

In my experience it can work quite well. I work alone on many projects. Given, you need support staff. I have someone to document everything aside from the most technical parts that I need to write myself. Also a project manager that extracts requirements and expectations from customers. Doing that myself would increase project duration tremendously.

It is pretty common in the embedded world in smaller companies. There just aren't enough developers to render enough support.

The problem with one-man-shows is the dependability. A lot of web developers go that route. But if they are unavailable because of private stuff or illness, the project they are working on is basically iced.

Re: Ask HN: Good ways to capture institutional knowledge?

#210

Post by k_bx » Mon, Mar 02, 2020, 2:57 PM UTC

I've recently made a small things called github-agent. Essentially it lets you keep your github issues as local markdown files. This helps keeping issue descriptions extensive and full of details as you work on them, since you can use your favorite editor (Emacs) to edit them and then sync in a simple terminal command.

https://github.com/k-bx/github-agent