Live data from Hacker News

Ask HN: Good ways to capture institutional knowledge?

news.ycombinator.com

31–40 of 220 posts

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

#31
I'll focus here on the knowledge of the key people you're about to lose. Ideas:

* If they're good at documenting, and willing to, task them to do as much of that as possible. The documenting might be in adding code comments and API docs, writing separate text files, etc. The person might not be able to document off-the-cuff, but have to work through a topic slowly, such as going through and re-understanding some old code themselves, going through a manual process that they do automatically and reflecting on the whys, etc.

* If some of the information is amenable to giving a talk to other employees, with a Q&A section, that might work, too.

* Another option is to have another employee interview the person leaving about one or more topics, and either type notes as they go, or record it and get a transcription. The interviewing person should be able to understand the topics.

* For tasks the person leaving does, you could have other people do the tasks while the person leaving is available for questions, and one of them documents as it goes. Depending on the task, it might make sense to have the knowledge-holder right there, both answering and observing, rather than only available for questions on-demand.

Side suggestion about accessibility/discoverability/maintainability of all this new documentation: consider keeping the medium simple, and avoiding a proliferation of locations, formats, a dozen bullpoop communication SaaSes, etc. For most software work, for example, inline embedded source code comments and API docs can be an easy way to try to keep a lot of information accessible in context and maintained. Some other information that doesn't fit well in source code, such as ops architecture and procedures, might be Markdown files in that same code repo, or another one. The occasional video file you just can't check into git might be a rare indispensible one, but can still be linked from a Markdown file that's in your repo, but even then, maybe you also have a text transcript in the repo, or someone turns a talk into edited docs in the repo.

Incidentally, much earlier in organizational knowledge sharing, I vaguely recall a study by a consulting firm (sorry, no cite handy, and I'm not 100% sure I remember which big-name firm), in which they found that people were resistant to having their knowledge captured in a system, because that knowledge was an asset of the individual. Your key people leaving might be more altruistic than that, want to help out their colleagues, want to have a good word-of-mouth reputation, have a sense of professionalism about it, have equity in the company, etc. You might like them to do knowledge transfer to a degree that's really above&beyond the call, so consider how you might acknowledge and thank them for that. It might also be a good example for others, and promote more proactive good practices for organizational knowledge.

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

#32
post #22

I'm not sure about the "successful companies institutionalize the knowledge of their employees" part. In such context a process becomes a (written) 'procedure/specification', and some folks stop innovating, they just do it "by the book". HR quickly grasps this and hires people with less and less skill, cheap personnel 'just able to apply to procedures'. Other ones feel like cogs in the machine (especially the best on…

This is why I have largely abandoned documenting procedures and instead write down "principles". As long as the principle is adhered to, the embodiment doesn't really matter.

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

#33
Write write write and keep writing. Then expect to do 10x as much reading. It's exhausting and definitely relies heavily on employees' writing and reading comprehension skills.

HashiCorp produces a mind boggling amount of prose (non-code text). Every employee can read every RFC going back to the first sketch of terraform which was completely rewritten in a second revision. Mailing lists are alive and well. PR descriptions and discussions are often longer than the code being changed.

No other company I've worked at has had this dedication to recording decisions, and all of them have struggled heavily with losing institutional knowledge. HashiCorp isn't perfect, but I want all future employers to at least pretend they're remote-first as that seems to be the forcing function for writing everything down.

Update: while writing skills are helpful they're definitely secondary to just ensuring knowledge is splatted down somewhere in some form. Perfect is absolutely the enemy of good enough, and I'd rather struggle to gleen knowledge from an unformatted readme in a deep dark corner than have nothing at all.

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

#34

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 it in some other program and have it use the logged-in user's credentials. Are you auditing your HR system before you log in, and are you sure that the "ls" you're invoking is the same "ls" that actually came from Debian? No? Then it all seems very pointless to me.

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

#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 year 1.

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

#36

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'd extend this to regular vacations too. I've worked a lot in both Europe and the USA. In Europe everyone had to know other people's knowledge as people were regularly out of the office. In the US it was easier to rely on someone as people rarely were out for a week and if they were they usually were local and on call.

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

#37

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…

That works for ops but not really for R&D. Your code will wait for 2 weeks, only running systems won’t.

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

#39
We record screencast videos demonstrating how to do a process. New people can watch those videos to learn how to do it.

If we find a better way to do something then we make a new video.

There's a team member who transcribes videos into google docs for people who like to read and search in google drive.

It's pretty simple and it works wonders for an international team.

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

#40
post #38

We work on https://usecodeflow.com , which is a way to capture the way code logically flows (especially used for new-hires to learn a new codebase). Feel free to email me in my profile if you want to chat!

Your website doesn't mention pricing at all before asking me to provide my github details. I dont know if the service will be free or I will be asked to pay until I provide my github credentials. My suggestion would be to add some info in the FAQs section.
Post reply on HN