In software engineering, we have a practice of consolidating knowledge in Design Docs, also called RFCs (Requests For Comments). E.g.
Google,
Uber. Overall, it is similar to SCM. When someone needs to build a new feature or change an existing system, they will write the proposal in a design doc and assign relevant stakeholders for a review. This process has two main goals:
1. To help the author solidify their knowledge. Oftentimes when I start writing a design doc, I feel that I already understand the problem and the solution. But in the process of writing I discover significant gaps in my knowledge, which lead me to change the details of my solution.
2. To reach an alignment between stakeholders. A design doc needs to be approved by all stakeholders before the actual work can begin. Peer-reviewing helps evaluate the solution from a diverse set of perspectives.
A good design doc will clearly outline a problem, set a concrete goal, provide a solution, and evaluate the solution from various perspectives (how does it compares to alternatives, what are the performance and security implications, any assumptions made, main risks and unknowns).
I like this practice and actively promote it to others. Here are some of the problems that commonly occur:
- Sometimes it's hard to follow what the author is saying. The knowledge exists in the author's head, but it's difficult to reconstruct it by reading the document.
- Sometimes the author doesn't have a sufficient understanding of the problem. By reading their document I can tell that they didn't dive deep enough, or didn't put enough effort to clarify the details. I find this annoying because it places a burden on me to identify gaps and persuade the author to fill them.
- Design docs quickly run out of date. Software systems evolve at a rapid pace. When I look at older design docs, I need to keep in mind that the information that was relevant at the time of writing may no longer be accurate or relevant at the time of reading.
- Design docs are narrow-scoped. They are only concerned with the goal at hand, and they disregard any irrelevant information. They are effective tools to make progress, but they don't paint a clear picture of the current state of technology. That's why we maintain engineering documentation as a separate resource to provide a high-level overview of the system. Design docs are for deep problem solving, and engineering documentation is for high-level knowledge sharing.
Overall, my stance is that knowledge exists in our heads. We use processes such as SCM and design docs to solidify our own knowledge and to align our knowledge with the knowledge of others. The artefacts of the process, such as SCM and design docs, don't fully capture the knowledge that we have, but they help their readers to form their own knowledge. Obtaining knowledge and sharing it with others requires investing time and effort. A pragmatic person knows how to balance the time spent researching and the time spent doing.
Intuitively, we think that sharing knowledge is an altruistic act, because it takes away someone's time for the benefit of others. But I think oftentimes it is not the case. For example, this comment is an artefact of knowledge sharing. I expect that 90% of the value generated from this comment is for my personal gain, from organising my thoughts on this topic, and I can only hope that it will generate at least some value for others.