Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: Good ways to capture institutional knowledge?

news.ycombinator.com

Post reply on HN
Print view View original

51–60 of 220 posts

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

#51

Post by DoreenMichele »

Don't assume that the architecture is even there for the institution to have control over everything. Small, young organizations are often relying on things they aren't fully aware of, like so-and-so has an uncle or a trust fund or a fast car or something.

When you talk to the outgoing employees, ask yourself if the processes they are describing are even processes that are replicable or controllable by the organization.

So, for example, are people putting things on their own credit card and getting reimbursed? Is this potentially a problem? Do you need to arrange a company credit card so the organization has real control here?

Then you need to document things. But don't just assume that the architecture is even there for the institution to be in control. You may need to create that piece as people leave.

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

#52

Post by raz32dust »

1. Working in pairs or teams. Avoid solo people working on projects.

2. Common, easily searchable place to put all documentation at. Good search capability is critical. Wiki is ok.

3. A good code & commit search engine. Ability to search code reliably obviates the need for a lot of documentation.

4. Weekly knowledge sharing sessions with the whole team. Both presenters and question askers need to be rewarded to keep engagement.

It is like replication in distributed systems. There are varying levels of redundancy you can get, and each higher levels involves higher overhead than the previous, so there is no golden rule - it needs to evolve as the organization evolves. A startup might have many people who are the only people who know certain things, but a 10000-person company surely should not have any institutional knowledge bound to one person.

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

#53

Post by luckydata »

woutr_be wrote: post #46
hlieberman wrote: post #9

Mandatory vacation. This is something that the finance industry has used for a long time to guard against fraud -- it's hard to cover up something if someone else has to do your job for two weeks straight at some point -- but it also serves as a mechanism for requiring you to cross-train people. Two weeks of paid vacation where the company isn't allowed to email them or call them for help: I guarantee that documentat…

I work as a software engineer in finance and have to take two weeks of mandatory vacation, but this doesn't deter our team from not writing proper documentation, or writing down domain specific knowledge. When someone is on leave who has specific knowledge, this is just planned into the sprint. As in "xxx knows most about this feature, so let's wait for him to return". Even when we do write documentation it just gets…

It just means people leaving are not that critical. If they were, you would have that documentation or you would be SOL pretty often.

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

#54

Post by ketzo »

Thorentis wrote: post #50

Confluence, or a similar private wiki is a good idea. As you work, write down steps to do things that were essential to doing part of your work, or things that you will need to repeat often. E.g. Create tutorials on setting up a development environment, installing dependencies, compiling modules, running tests, creating new components. Write descriptions at a high level of the system, make diagrams of complex message…

+1. Atlassian tools catch some flack (for good reason), but I worked at a company where anytime someone had a question that their immediate neighbor couldn’t answer, the response was “try checking Confluence, I usually find stuff there”. It made my onboarding SUPER easy because I could basically Wikipedia every internal process/setup/best practice. Awesome feeling.

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

#56

Post by dehrmann »

raz32dust wrote: post #52

1. Working in pairs or teams. Avoid solo people working on projects. 2. Common, easily searchable place to put all documentation at. Good search capability is critical. Wiki is ok. 3. A good code & commit search engine. Ability to search code reliably obviates the need for a lot of documentation. 4. Weekly knowledge sharing sessions with the whole team. Both presenters and question askers need to be rewarded to keep…

> Common, easily searchable place to put all documentation at. Good search capability is critical. Wiki is ok.

I have mixed feelings around documentation because I can often read the code faster than the docs, and docs are often incomplete, inaccurate, and out-of-date. Docs for truly long-lived things are nice, though.

As for good search, that's easier said than done. The heuristics Google used for search don't work in code, and searches are too rare to do useful ML for relevancy.

Edit: seeing the downvotes...

I don't actually mind writing documentation, but more often than not, I've found people like(?) writing it because it makes them feel like they're improving the situation by doing something. I'd rather the effort be spent on better naming and factoring in code. Docs are also very prone to rot and drift.

That said, I've found Java docs, MDN, and most man pages to be very good, in part because of how thought-out the docs are and how static the interface is. I'm also a fan of docs that bootstrap new developers. Someone else said they like docs describing "principles," and I like that idea--guidance so you know what A should do vs. what B should do.

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

#57

Post by et2o »

jrockway wrote: post #34
hlieberman wrote: post #9

Mandatory vacation. This is something that the finance industry has used for a long time to guard against fraud -- it's hard to cover up something if someone else has to do your job for two weeks straight at some point -- but it also serves as a mechanism for requiring you to cross-train people. Two weeks of paid vacation where the company isn't allowed to email them or call them for help: I guarantee that documentat…

I worked in the finance industry and took the mandatory 2 week vacation and dealt with my coworkers taking the mandatory 2 week vacation. We didn't write any documentation or have any internal wiki or anything like that, and everything seemed fine. I also find it pretty questionable that someone couldn't write a computer program that can embezzle unattended for two weeks. You don't use your own credentials, you stick…

that is not how 99.99% of embezzlement works. No one in finance is using 0-days (or whatever) against their own companies. It would be much more "routine" types of practices, which might be noticed given minimal oversight.

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

#58

Post by woutr_be »

luckydata wrote: post #53
woutr_be wrote: post #46

Earlier quoted context omitted.

I work as a software engineer in finance and have to take two weeks of mandatory vacation, but this doesn't deter our team from not writing proper documentation, or writing down domain specific knowledge. When someone is on leave who has specific knowledge, this is just planned into the sprint. As in "xxx knows most about this feature, so let's wait for him to return". Even when we do write documentation it just gets…

It just means people leaving are not that critical. If they were, you would have that documentation or you would be SOL pretty often.

I don't think it "just" means that people are not that critical, it's a much deeper issue. All the way from individual engineers to managers to product owners to the company in general.

At least in my team, is see:

- Managers allowing people to only take on specific work, therefore people are becoming highly specialised

- Individual developers don't push others to write documentation, instead they wait until somehow they have to do a task, spend 2 weeks to figure it out, and then write some documentation around it

- Individual developers who force themselves to only work on specific pieces. (I think mostly to fuel their ego so they're needed)

- The company not encouraging knowledge sharing, or simply not providing good tools for it

- Product owners who don't really care about the product

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

#59

Post by o-__-o »

et2o wrote: post #57
jrockway wrote: post #34

Earlier quoted context omitted.

I worked in the finance industry and took the mandatory 2 week vacation and dealt with my coworkers taking the mandatory 2 week vacation. We didn't write any documentation or have any internal wiki or anything like that, and everything seemed fine. I also find it pretty questionable that someone couldn't write a computer program that can embezzle unattended for two weeks. You don't use your own credentials, you stick…

that is not how 99.99% of embezzlement works. No one in finance is using 0-days (or whatever) against their own companies. It would be much more "routine" types of practices, which might be noticed given minimal oversight.

The proper way to embezzle is by making $20-$100 addons to thousand dollar purchases. You don’t want hundreds of thousands papertrailing back to you. You don’t buy a boat on the company dime you buy trinkets to put on your boat. The real embezzlers are taking $3-$5k/year. The ones taking more end upon the 5 o’clock news

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

#60

Post by cheschire »

richardw wrote: post #35

People who have been in the job for a while aren’t always the best people to explain something. What I’ve often done is asked new hires to document what they discover. New people are easier to mould to a new behaviour and often have the questions you need to know. When documenting becomes the habit, more people do it. Current 500-person company is very good at documenting many aspects, because we’ve done it since yea…

This is what we do. It has the added benefit of forcing new people to read the documentation that was left for them. It’s been my experience that without this directed task, they won’t even look at existing documents. Tell them it’s a deliverable and suddenly they read everything.
Post reply on HN