Update 2023-12-16 更新 2023-12-16

Hello readers, some minor clarifications to this post. On 2023-12-12 I made it to the front page of Hacker News! As is tradition this made many people upset and and has been widely regarded as a bad move. I want to add a few notes based on feedback I got in: https://news.ycombinator.com/item?id=38614195.
读者您好，对这篇文章进行一些小的澄清。2023-12-12 登上了 Hacker News 的头版！按照传统，这让许多人感到不安，并被广泛认为是一个糟糕的举动。我想根据我收到的反馈添加一些注释：https://news.ycombinator.com/item?id=38614195。

• The author confused Tacit Knowledge with Tribal Knowledge, they are different things!
  作者混淆了隐性知识和部落知识，它们是不同的东西！
  • Okay, it’s fair that they are defined differently. I will accept that Tacit knowledge is considered knowledge gained through experience, whereas Tribal Knowledge is information not written down that people keep in their heads. However I do not feel that means that Tacit Knowledge cannot be written down nor is it worthwhile to write down what you know. Saying that something is only learnable through experience and cannot be written down means that the ideas can never be challenged nor explained. “We will use the database with these settings because I have 10 years of database experience” is not testable. Saying “We use the database with these settings because it meets these performance criteria and avoids issues with X” allows for testing, shares experience, and opens the door to opportunities for improvement.
    好吧，它们的定义不同是公平的。我会接受隐性知识被认为是通过经验获得的知识，而部落知识是人们脑海中没有写下来的信息。然而，我不觉得这意味着隐性知识不能被写下来，写下你所知道的也不值得。说某些东西只能通过经验来学习，不能写下来，这意味着这些想法永远无法被挑战或解释。“我们将使用具有这些设置的数据库，因为我有 10 年的数据库经验”是不可测试的。说“我们使用具有这些设置的数据库，因为它满足这些性能标准并避免了 X 的问题”，可以进行测试，分享经验，并为改进机会打开大门。
• It takes too long to write down documentation!
  写下文档需要很长时间！
  • If your work becomes important enough it will take longer to explain it over and over.
    如果你的工作变得足够重要，那么一遍又一遍地解释它将需要更长的时间。
• You can’t possibly document everything!
  你不可能记录所有事情！
  • I agree, but you can try your best to capture everything that seems important or reoccurring.
    我同意，但你可以尽力捕捉所有看似重要或反复发生的事情。

I’ve decided to capture these points rather than re-write my post to acknowledge that they are valuable, but since I object to them, I’m not going to change the original content.
我决定捕捉这些要点，而不是重写我的帖子以承认它们很有价值，但由于我反对它们，我不打算更改原始内容。

Original Post 原始帖子

Tacit knowledge, often called “tribal knowledge” in tech, is prevalent in this industry. Documentation is a common afterthought and is frequently wrong, out of date, or lacking crucial information. New hires join a company and go through onboarding exercises intended to have them learn by doing. Often that learning means asking others when they get stuck. It becomes natural for an engineer to end up having key information in their head. When others need it, the engineer freely shares it. Until, the inevitable happens.
隐性知识，在技术中通常被称为“部落知识”，在这个行业很普遍。文档是常见的事后想法，经常是错误的、过时的或缺少关键信息。新员工加入公司并进行入职练习，旨在让他们在实践中学习。通常，这种学习意味着在别人遇到困难时询问他们。对于工程师来说，最终将关键信息放在他们的脑海中是很自然的。当其他人需要它时，工程师可以自由分享它。直到，不可避免的事情发生了。

You need to know something not written down. You won’t be able to get an answer for a long time from the person who knows it best.
你需要知道一些没有被写下来的东西。在很长一段时间内，你都无法从最了解它的人那里得到答案。

The person who knows what you need is not there. Maybe they left the company, maybe they are on vacation. You may really need to know about the whizbang service, but it’s been 4 years since anyone last worked on it and no-one remembers how it works. You’ve now fallen into the trap of tacit knowledge.
知道你需要什么的人不在那里。也许他们离开了公司，也许他们正在度假。您可能真的需要了解 whizbang 服务，但是自从有人最后一次使用它以来已经有 4 年了，没有人记得它是如何工作的。你现在已经掉进了隐性知识的陷阱。

It’s easy, even efficient, to rely on tacit knowledge early on. It is often called tribal knowledge because it’s shared by people close to you, the proverbial tribe. This passing on of knowledge helps bond junior and senior members. The tribe passes this knowledge from seniors to juniors via rituals of song and dance. These songs will take form of video calls, ☕chats, instant message exchanges. Dances transmit information by moving the hand to ctrl+c from a notebook of useful commands, and pressing ctrl+v to send to a colleague. Other more advanced dances involve connecting to a colleagues machine to fix an issue or show a manual setup process that isn’t written down. These song and dance routines will hit their limit at some point.
在早期依赖隐性知识是很容易的，甚至是有效的。它通常被称为部落知识，因为它是由你身边的人分享的，这就是众所周知的部落。这种知识的传递有助于将初级和高级成员联系起来。部落通过歌舞仪式将这些知识从老年人传给年轻人。这些歌曲将采用视频通话、☕聊天、即时消息交流的形式。舞蹈通过将手移动到有用命令的笔记本中的ctrl+c，然后按ctrl+v发送给同事来传递信息。其他更高级的舞蹈包括连接到同事的机器以解决问题或显示未记录下来的手动设置过程。这些歌舞套路会在某个时候达到极限。

Graph showing relative time scales for different ways of learning something at work.
图表显示了在工作中学习某些东西的不同方式的相对时间尺度。

Where sharing tribal knowledge breaks down is at scale. It’s faster to shoot someone who knows the answer a message than to read the documentation, but only if that wise sage can respond quickly. If the holder of the knowledge is busy, in another timezone and you missed the end of their day, or are on vacation, you are out of luck until they return. The timezone problem is particularly painful. 3:30 pm pacific has 1.5 hours left in the 9 - 5 working day. But if you need help from someone on the east coast of the US, it’s 6:30 pm and they have gone home. That same time is 8 am in Australia, and 4 am in India. If you need help from someone on the other side of the world, you’ll be waiting for a while. This doesn’t even attempt to account for different countries having their own set of national holidays.
分享部落知识崩溃的地方是大规模的。向知道答案的人发送消息比阅读文档要快，但前提是那个聪明的智者能够迅速做出反应。如果知识的持有者很忙，在另一个时区，而你错过了他们的一天的结束，或者正在度假，那么在他们回来之前，你就不走运了。时区问题尤其令人痛苦。下午 3：30 太平洋地区在 9 - 5 个工作日还剩 1.5 小时。但是，如果您需要美国东海岸某人的帮助，现在是下午 6：30，他们已经回家了。同样的时间是澳大利亚早上 8 点，印度是凌晨 4 点。如果你需要来自世界另一端的人的帮助，你会等待一段时间。这甚至没有试图解释不同的国家有自己的一套国定假日。

As a company scales, reliance on tacit knowledge becomes more of a burden. The amount of time it takes to answer a question is a blocker and needing to ask someone begins to consume more time due to both timezones as well as the busy nature of some senior people.
随着公司规模的扩大，对隐性知识的依赖变得越来越沉重。回答一个问题所需的时间是一个障碍，由于两个时区以及一些老年人的忙碌性质，需要询问某人开始消耗更多时间。

Graph showing how it takes a long time to get answers when distributed. Asking a fourth question doesn’t even fit on the “large, distributed” row.
该图显示了在分发时如何需要很长时间才能获得答案。提出第四个问题甚至不适合“大型、分布式”行。

The longer it takes to get answers, the longer an engineer is blocked. These blockers begin to act as a drag on the ability of an engineer to be productive, and at scale slows down the company itself. Features took longer to ship, bugs take longer to fix. The company itself becomes less nimble and vulnerable to smaller players. This situation always existed, but was exacerbated by COVID and the rise of remote work. Coworkers that used to sit next to each other would now work from home. People moved to different cities, and sometimes moved across timezones. How then, can one try to regain productivity?
获得答案的时间越长，工程师被阻止的时间就越长。这些阻碍因素开始拖累工程师的生产力，并且大规模地减慢了公司本身的速度。功能需要更长的时间才能发布，错误需要更长的时间来修复。公司本身变得不那么灵活，容易受到较小参与者的攻击。这种情况一直存在，但由于 COVID 和远程工作的兴起而加剧。过去坐在一起的同事现在可以在家工作。人们搬到了不同的城市，有时甚至跨时区移动。那么，如何才能尝试恢复生产力呢？

Graph showing how reading docs and watching videos is still slower than asking people who know (and can respond quickly) but far faster than waiting for large, distributed teams to reply to you.

The answer lies in the original chart: As teams scale up and knowledge becomes more distributed, it is faster to read documentation and watch video lectures than it is to ask others for help. Personally, I am an avid reader and prefer reading (and grepping) for what I need to know. Others learn topics better through video lectures and that is fine. Both have a place, but documentation should always be there because it is easily searchable and easy to reference. By investing the time to create a library of information, both written and video, a middle ground is reached. It will never have that small co-located team efficiency, but it will scale far better than anything relying on tacit knowledge.

For those who need help in getting started with writing documentation, a previous blog post of mine discusses that as well. Good Docs Take Great Effort is where I would suggest anyone start when they need to figure out how to write documentation or see where they may improve.