Having a single wiki instance for your company is an awesome way to collect knowledge. You can write up operation run books, design documents, references all in an informal way.
This gets out of date quickly if this is not curated in some way.
Ask HN: Good ways to capture institutional knowledge?
21–30 of 220 posts
Re: Ask HN: Good ways to capture institutional knowledge?
#22I'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 ones, hunted by competitors) and quit.
Someone departing with the 'procedures' may let a competitor obtain a rather complete grasp of it and adopt the best bits.
Letting each team decide about this and establish cross training seems preferable to me, and has many other benefits.
Re: Ask HN: Good ways to capture institutional knowledge?
#23If a system is not documented in terms of what it does, how it does it, and common remediations for when things go wrong, then it's a fragile system depending on one person to keep it going.
You need to get (particularly, senior) engineers to buy into the mindset of documenting everything and making the documentation the first place to look (not after all else fails). Leads should hold be held accountable for their docs meeting some standard of "this is a useful doc".
If I were in your shoes I'd get senior engineers in a room and be honest with them about the situation. You're going to need them to do work that they might not be naturally inclined to do, or work that might not seem like a "productive" use of time. You might want to get them to agree on what a good doc looks like (the standard), and what things need to be documented. Maybe take a whole day to do this, with snacks and coffee. Good luck!
Re: Ask HN: Good ways to capture institutional knowledge?
#24One of the things I practice personally is more-or-less documentation driven development: https://gist.github.com/zsup/9434452 Although I'm using writing developer-level code, so I'm not literally writing end-user documentation. But I follow the principle; I generally start any significant function by first writing the documentation for it at the appropriate level of detail.
I usually also try to budget a day or two at the end to look at the documentation and generally clean it up. I can't always get "fresh eyes" on it per se but at least I can make sure it seems to basically flow.
The side effect is your major project also comes with basic documentation for very cheap. Honestly, it may even be "cheaper than free"; I do this because I think it helps make better code, faster. The act of writing the documentation doubles as a self-directed design review, and I couldn't even tell you the number of times I've documented some particular thing only to realize how stupid it is before I even wrote a single line of code [1], and started rearranging things at the cheapest development stage there is. But I concede in advance that proving it's "cheaper than free" is pretty hard.
I don't present this as a full organizational solution, of course, but unlike those full organizational solutions, this is something anyone reading this can pick up and start trying out tomorrow, whereas "redo how our organization conceives of how we store information" is a bit less immediately actionable, shall we say.
[1]: "Wait, I'm requiring what precondition of the callers? Wait, I'm going to return six values? (Better make a new struct/class/object.) I seem to have an awful lot of functions asking for the same 4 parameters (again, new struct/class/object). I'm asking for how many incoming parameters? These are awfully complicated instructions I'm giving about what they can and can't do to the return values. These instructions on the transactionality of this call are stupid complicated." etc.
Re: Ask HN: Good ways to capture institutional knowledge?
#25You’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 review each other's pull requests effectively and go to each other for questions.
I'm not sure I like the pair programming or the open office environment, but I haven't tried anything else yet. Sometimes I think pairing slows us down. And we sit right next to a tech support team that's on the phones all day...
Re: Ask HN: Good ways to capture institutional knowledge?
#261. Wiki w/ comments
2. Corporate university
3. Culture of anti-knowledge hoarding, pro automation, well-documented procedures and no "we need Joe, only he knows how to do vital task X."
4. Succession planning
Re: Ask HN: Good ways to capture institutional knowledge?
#27A per-project or per-process README would be a good first step. Ideally keep the notes/instructions as close to the place where the work will get done. It's important for someone to test the instructions in the README on a new machine --- 9 out of 10 times you'll find a step about authentication or some system dependency was not documented. Credentials are extra tricky, so you'll have to think extra hard how to make that work (e.g. some sort of central key store, shared password manager, or ENV vars that need to be defined so you avoid putting any sensitive info in the README).
For something even better than a README, you could document the steps of a technical procedure in a Makefile (or Fabfile) that your colleagues can run. It's important to keep the scripts readable and stupid (as opposed to abstract and powerful like ansible), so that people can read the steps. Some people refer to this as "runnable documentation."
Re: Ask HN: Good ways to capture institutional knowledge?
#28The pushback will come from two places: people who can't write (the overwhelming majority of people) and people who usually act impulsively and without a sound basis (also the great majority of people). The presence of these classes of people in a company will lead to the punishment of people who can and do write, for two reasons. The non-writers won't be able to tell that the writers have done something useful and therefore won't be able to highlight it as an accomplishment in peer or manager evaluations. The irrational actors will get all the accolades for "having impact" even when their random, unjustifiable activities have clearly harmed the company. Meanwhile the people who were writing the design docs will be judged for having less impact.
The way I like to measure this is there should be more writing than programming going on within the company. Some investigations, research efforts, or designs will lead to nothing, however every implementation should come with research, design, and retrospective documentation. In that case there will always be at least as many written artifacts as programs.
The way to prevent the nightmare of an illiterate workforce with only oral history is to hire people who can write and practice documentation-driven development, instead of hiring people who can memorize leetcode trivia.
Re: Ask HN: Good ways to capture institutional knowledge?
#29Earlier quoted context omitted.
Why is email superior to slack (or other chat solutions)?
Can you export slack logs as plain text, or something easy to process like JSON? (Haven't used it in forever, so I don't know). Being able to grep -A3 -i foobox -r /nfs/info | grep -i rpc is useful. Similarly, you can shove plaintext into a more advanced search engine easily.
> Can you export slack logs as plain text, or something easy to process like JSON?
I think you can, the main issues are that:
- Conversations aren't forced to be threaded, and there is no way to go back and do anything with conversations that weren't threaded; it's just lost data.
- Because Slack doesn't export data into a standardized format, there isn't a big ecosystem of tools to do stuff with Slack data. And it's not clear that there will be in the future either -- Slack's growth has started slowing substantially and it's only around 13M DAU, which isn't really big enough to build a business on top of.
Re: Ask HN: Good ways to capture institutional knowledge?
#30Force people to stop asking the most experienced person to answer questions or solve problems.
Have people document how they diagnosed problems after fixing it, including queries for searching logs.
Thank people for documenting things.