In the summer of 2001, a mid-sized pharmaceutical company lost its entire formulation chemistry expertise over eighteen months. Three senior scientists retired. Two others left for competing companies. The knowledge they carried — accumulated over combined decades of trial, error, and refinement in a highly specialized domain — left with them. The company had patents. It had equipment. It had data tables. What it did not have was the explanatory knowledge that made those data tables interpretable: the understanding of why certain combinations worked, which variables mattered most under which conditions, and how to diagnose problems when experiments produced unexpected results. Reconstructing that knowledge cost years and millions of dollars.

When Ray Dalio, founder of Bridgewater Associates, began writing down the principles that guided his decision-making, he did not intend to create a book. He started with short memos to his team explaining why he made specific investment decisions, what factors he weighed, and what patterns he had observed across decades of managing the world's largest hedge fund. Over years, these memos accumulated into a comprehensive framework for decision-making that could be studied, debated, and applied by anyone at the firm — not just Dalio himself. When he eventually published Principles in 2017, it became a bestseller not because of elegant prose but because it represented something rare: tacit expertise made explicit and transferable.

Knowledge writing is the practice of converting expertise from the minds of individuals into written form that can be understood, used, and built upon by others. It is one of the most valuable and most consistently under-practiced professional capabilities. Almost every organization has more undocumented expertise than documented expertise. Almost every professional carries knowledge that would be valuable to others if it were accessible.

"The biggest threat to organizational knowledge is not that people leave. It is that knowledge was never written down in the first place." — Adapted from Nonaka and Takeuchi, The Knowledge-Creating Company (1995)

The Knowledge Types That Need Writing

Knowledge Type Description Difficulty to Capture Primary Method
Explicit Facts, procedures, specifications Low Direct documentation
Tacit Expert judgment, pattern recognition, "feel" High Observation, retrospective protocol
Contextual Organization-specific history, trade-offs, informal dynamics Medium-High Storytelling, annotated decisions

Not all knowledge is equally difficult to capture in writing. Understanding which knowledge types are hardest to transfer — and why — clarifies what knowledge writing is actually for.

Explicit Knowledge

Explicit knowledge is knowledge that can be stated directly: facts, procedures, specifications, formulas. "The boiling point of water at sea level is 100 degrees Celsius." "To submit a purchase order, navigate to the Finance portal and complete form PO-2023." Explicit knowledge is relatively straightforward to document. It is also the knowledge type that most organizations document reasonably well — because it is the type that can be captured by an administrative function without requiring deep expert engagement.

Tacit Knowledge

Tacit knowledge is the knowledge that experts have difficulty articulating — the "feel" for whether something is right, the pattern recognition that comes from years of experience, the judgment about when to apply which approach. Michael Polanyi, who introduced the concept in 1966, described it with the phrase: "We know more than we can tell."

A master surgeon knows more about tissue feel than they can write in a textbook. An experienced negotiator reads a counterpart's reactions in ways they cannot fully articulate. A seasoned engineer has intuitions about system failure modes that would take hours to explain completely. This is tacit knowledge: real, valuable, transmissible through apprenticeship but difficult to transmit through writing.

Knowledge writing is fundamentally the project of making tacit knowledge explicit — not completely (that is often impossible) but as much as is practically useful for the audience.

Contextual Knowledge

Contextual knowledge is expertise about a specific environment: why this organization makes particular trade-offs, what the history is behind a specific decision, which informal relationships matter for getting things done, what has been tried before and why it failed. New employees arrive with plenty of general expertise and no contextual knowledge; the gap is what makes onboarding expensive and long tenure valuable.

Contextual knowledge is chronically under-documented because it seems obvious to those who have it. The people with the most contextual knowledge — long-tenured employees, founders, institutional leaders — find it most difficult to imagine what someone without that knowledge would not know.

The Expert Curse and How to Overcome It

The central challenge in knowledge writing is the expert curse (related to the "curse of knowledge" described by economists Colin Camerer, George Loewenstein, and Martin Weber in a 1989 paper): experts forget what it was like not to know what they know. They skip steps that seem obvious. They use jargon without defining it. They describe conclusions without explaining the reasoning that led to them.

The result is documentation that satisfies the expert author — it is accurate, after all, and covers everything important — while failing to help the intended audience, who lack the background to fill in the missing steps.

Several techniques reliably counteract the expert curse.

The Stranger Test

Before finalizing any knowledge document, apply the stranger test: Could a competent professional with no background in this specific area read this document and successfully apply its contents without asking questions?

The test requires imagination — conjuring a specific reader who is real enough that you can identify what they would and would not know. A useful framing: think of someone you know who is intelligent and professionally capable but who is brand new to this domain. What would they be confused by? What steps would they not know how to take? What jargon would they not recognize?

Every identified confusion is a gap in the documentation.

The Retrospective Protocol

Capture knowledge while the expert is actively doing the work, not after. Gary Klein's cognitive task analysis methodology, developed for military and aviation training, identifies expert knowledge through observation and structured retrospective interviewing: watching an expert perform a task, then asking them to explain each decision as they made it.

The retrospective protocol is more effective than asking experts to write documentation because it bypasses the expert curse partially — the expert is responding to concrete decisions they just made rather than abstractly describing what they know. The resulting explanations are more complete, more specific, and more likely to include the contextual judgment factors that get lost in abstract documentation.

The Five-Level Why

When an expert provides an explanation, ask "why?" — then ask "why?" again for the answer, and again, and again. After five iterations, the explanation has typically reached a fundamental principle rather than a context-specific application.

Example: An expert documents: "When the system produces error code 503, restart the application server."

  • Why? "Because error 503 indicates the application server has run out of memory."
  • Why does it run out of memory? "Because certain API calls create objects that are not garbage collected."
  • Why are those not garbage collected? "Because of a known bug in the third-party library version we use."
  • Why haven't we upgraded the library? "Because version 3.x breaks compatibility with our authentication module."
  • Why has that not been resolved? "It is on the roadmap for Q2 but has not been prioritized."

The five-level why produces documentation that includes not just the procedure but the explanation that allows the reader to understand when the procedure applies, why it works, and what constraints shape it.

The Structure of Effective Knowledge Documents

Knowledge writing is not just about capturing content — it is about organizing that content in a form that serves how the reader will use it. Different knowledge types have different optimal structures.

The Decision Record

When organizational decisions are made — technical architecture choices, product direction pivots, policy changes, process redesigns — the reasoning behind them is almost never documented. The decision is implemented; the rationale exists only in the minds of the people who were in the room. When those people leave, or when the decision is revisited months later, the absence of documented rationale produces costly re-argumentation of settled questions or inappropriate reversal of well-reasoned decisions.

Architecture Decision Records (ADRs), popularized in software engineering by Michael Nygard in 2011, provide a lightweight template for capturing decisions. A standard ADR records:

  • The decision
  • The context that prompted it (what problem was being solved, what constraints existed)
  • The options considered
  • The rationale for the chosen option
  • The consequences (expected trade-offs of the decision)

The ADR structure is not just for software architecture. Any significant organizational decision benefits from the same documentation approach: what was decided, why, and what trade-offs were accepted.

Example: Amazon Web Services maintains detailed internal decision records for major architectural choices. When engineers join teams, access to these records significantly reduces the onboarding time needed to understand why the system is structured as it is — and more importantly, prevents the rework that occurs when new engineers, not knowing why a decision was made, reverse it based on reasoning that was already considered and rejected.

The Process Guide

Process documentation captures how work is done: the sequence of steps, the decision points, the common failure modes, and the escalation paths. Good process documentation is executable by someone doing the process for the first time, under realistic conditions.

The most common process documentation failure is the assumption that the reader shares context with the author. Experts document what to do without documenting how to recognize when to do it, how to handle exceptions, or what to do when steps produce unexpected results.

A rigorous process documentation structure:

  1. Purpose: What outcome does this process produce?
  2. Trigger: When and why is this process initiated?
  3. Preconditions: What must be true before the process begins?
  4. Steps: Numbered, specific, with decision branches for variations
  5. Exception handling: What to do when steps produce unexpected results
  6. Outputs: What the completed process produces
  7. Escalation: When and how to get help if the process cannot be completed

The Explanation Document

Some knowledge is primarily conceptual: understanding why a system works as it does, what the principles are that guide a particular domain, how to think about a class of problems. This knowledge does not fit into procedure documentation because it is not a sequence of steps — it is a framework for understanding.

Explanation documents are among the most valuable and most rare forms of organizational knowledge writing. They require experts to articulate the mental models they have developed, not just the procedures they follow. The Feynman Technique — explaining a concept as if to someone without specialist knowledge — is the most effective method for developing explanation documentation: if the explanation requires technical vocabulary to be understood, it is not yet fully understood by the writer.

Knowledge Writing for Specific Professional Contexts

For Individual Professionals

Individual professionals accumulate knowledge that is valuable beyond their current role — understanding of domain patterns, frameworks they have developed for specific problems, lessons learned from projects that went well and poorly. Writing this knowledge down serves two purposes: it clarifies the expert's own thinking (the act of writing forces precision that internal thought does not), and it creates transferable assets that can be shared.

Career benefits of knowledge writing:

  • Demonstrated expertise: Published writing — in internal wikis, external blogs, or industry publications — makes expertise visible beyond direct relationships
  • Intellectual asset creation: Notes and frameworks created through knowledge writing can become training materials, consulting offerings, or published work
  • Personal clarity: Many experienced professionals report that the discipline of knowledge writing improves their own decision-making by forcing explicit articulation of reasoning they had been applying intuitively

Example: Will Larson, an engineering executive, writes extensively at lethain.com about engineering management and organizational design. The writing began as a way to capture and clarify his own thinking; it became one of the most widely cited resources in engineering management, and eventually became his book An Elegant Puzzle. The knowledge writing served his career before it became a published product.

For Organizations

The organizational case for knowledge writing is straightforward: institutional knowledge that exists only in employees' heads is at permanent risk of loss, cannot be leveraged across teams, and cannot scale beyond individual relationships. Organizations that invest in systematic knowledge writing reduce the knowledge attrition cost of turnover, accelerate onboarding, and enable organizational learning at scale.

The investment required is not primarily technological — the tools for knowledge writing are generic and inexpensive. It is cultural and process-based: making knowledge documentation a recognized part of professional work, not an afterthought. This requires:

  • Including documentation in the definition of done for projects
  • Allocating time in estimates for knowledge capture
  • Recognizing knowledge writing contributions in performance evaluation
  • Providing feedback on knowledge writing quality rather than treating all documentation as equally good

The Onboarding Use Case

One of the highest-leverage applications of knowledge writing is onboarding documentation. The cost of slow or ineffective onboarding — the time new employees spend getting up to speed, the errors they make from missing context, the opportunity cost of not contributing effectively during the ramp-up period — is substantial.

Organizations that invest in comprehensive onboarding knowledge writing consistently report faster time-to-productivity for new employees. The documentation required is not a policy manual — it is the contextual knowledge that long-tenured employees take for granted: how things actually work rather than how they are officially supposed to work, who to ask for what, what decisions have been made and why, what the organization's current priorities actually are in operational terms.

For related frameworks on writing clearly so knowledge transfers effectively, see writing for clarity and documentation tools explained.

What Research Shows About Knowledge Transfer and Documentation

The academic study of organizational knowledge has been shaped most significantly by two researchers whose work spans multiple decades. Ikujiro Nonaka and Hirotaka Takeuchi, in The Knowledge-Creating Company (1995), introduced the SECI model -- Socialization, Externalization, Combination, Internalization -- to describe how tacit knowledge moves through organizations. Their central finding, based on comparative study of Japanese and American manufacturing companies, was that the organizations with the most effective knowledge transfer were not the ones with the most extensive documentation but the ones with processes for converting tacit knowledge into explicit form and then creating conditions for internalization of that explicit knowledge.

Nonaka and Takeuchi's research identified a specific failure mode that affects most professional knowledge documentation: externalization without internalization. Organizations invest in documentation -- writing procedures, capturing processes, creating wikis -- without creating conditions for new employees to internalize the documented knowledge. The documentation exists but is not used, because reading a document is not the same as developing the mental model that the document was meant to represent. Their research suggested that knowledge writing is necessary but insufficient for knowledge transfer; it must be accompanied by practice opportunities, mentoring, and feedback.

Gary Klein, cognitive psychologist and author of Sources of Power (1999), developed Cognitive Task Analysis (CTA) as a method for extracting tacit knowledge from expert practitioners. Klein's research, originally conducted for the U.S. Army and later applied across aviation, medicine, firefighting, and engineering, demonstrated that the most effective technique for capturing expert knowledge is not interviewing experts about what they know but observing them making decisions and asking them to explain each decision as they make it.

Klein found that experts consistently underestimate the complexity of their decision-making when asked to describe it retrospectively and abstractly. An expert who says "I just knew something was wrong" when asked to explain a correct diagnosis will, when observed making a similar diagnosis, produce a detailed description of the specific cues, pattern comparisons, and mental simulations that drove the conclusion. Klein's CTA methodology captures this real-time knowledge, producing documentation of decision processes that is significantly more complete and actionable than documentation produced by asking experts to write about what they know.

Michael Polanyi's philosophical analysis of tacit knowledge, introduced in The Tacit Dimension (1966), established the theoretical frame within which all subsequent knowledge transfer research operates. Polanyi's famous formulation -- "we know more than we can tell" -- describes a genuine epistemic condition: some knowledge exists as embodied skill or intuition that resists complete articulation. The practical implication for knowledge writing is not that tacit knowledge cannot be written but that it requires specific techniques -- worked examples, annotated decision records, narrative accounts of failure and recovery -- to approach in writing what can only be fully transmitted through apprenticeship.

Steven Pinker's research on expert communication, summarized in The Sense of Style (2014), applies the curse of knowledge specifically to knowledge writing. Pinker found that experts writing for non-experts consistently underestimate how much background knowledge their readers lack, and overestimate how much can be inferred from the written text. The solution Pinker recommends -- write for a specific known non-expert, not for an abstract audience -- is particularly applicable to knowledge writing, where the gap between expert author and non-expert reader is typically large and the cost of the gap is high.

Case Studies: How Organizations Captured Knowledge That Would Otherwise Be Lost

Ray Dalio and the Bridgewater Principles

Ray Dalio began writing decision memos at Bridgewater Associates in the 1980s as a response to a specific organizational problem: as the firm grew, investment and management decisions that Dalio had made based on accumulated judgment could no longer be transmitted through direct mentorship to all decision-makers in the organization. He needed a way to make his judgment available to people he could not personally supervise.

Dalio's methodology was systematic. After each significant decision -- a successful trade, a failed prediction, a management call that went wrong -- he wrote a memo explaining the principles he had applied, why he had weighted different factors as he did, and what he would do differently in hindsight. Over twenty years, these memos accumulated into several hundred pages of explicit decision-making frameworks. The collection became the basis for internal training at Bridgewater, was eventually formalized into a management system, and was published as Principles: Life and Work in 2017.

The Bridgewater case demonstrates the compounding value of systematic knowledge writing: individual memos that were modestly useful when written became substantially more valuable when accumulated into a pattern-revealing corpus. The knowledge became more explicit with each iteration, as Dalio was forced to articulate principles in enough generality to apply across situations while maintaining enough specificity to guide actual decisions.

NASA's Lessons Learned Information System

Following the Apollo 1 fire in 1967, NASA developed the Lessons Learned Information System (LLIS) to capture knowledge from program failures and successes in a form that could be retrieved and applied by future program teams. The system was designed specifically to address a failure mode that the Apollo 1 investigation had identified: similar problems had occurred in earlier NASA programs and had produced informal lessons that were not captured in retrievable form. Engineers working on Apollo had not known about relevant precursors.

The LLIS database accumulated thousands of entries over subsequent decades. A 2004 review of the system by NASA's Office of the Inspector General found, however, that the knowledge capture was more successful than the knowledge transfer. Engineers submitted lessons; fewer engineers retrieved and applied them. The review identified structural problems in how lessons were written -- most were written at a high level of technical specificity that made them retrievable only by engineers with the exact problem context of the original case, limiting their applicability to adjacent problem types.

The review produced revised guidelines for lesson writing that emphasized: stating the lesson at a level of generality that made it applicable to similar rather than identical situations, including the context of the original failure in enough detail that readers could judge applicability, and expressing the lesson as a decision principle rather than a compliance rule. The revised guidelines represent one of the most thoroughly studied examples of how the structure of knowledge writing affects its subsequent utility.

Stripe's Internal Documentation Culture

Stripe, the payments technology company, has developed a reputation for unusually high-quality internal documentation, described by multiple current and former employees as a competitive advantage in a technical domain where documentation quality is often poor. The documentation practice is not accidental -- it is enforced through specific organizational norms.

At Stripe, documentation is part of the definition of done for engineering projects: a feature is not considered complete until its architecture, design decisions, and operational procedures are written in the company's internal wiki. Engineers who join the company are evaluated partly on documentation quality in addition to code quality. Technical design documents are required before implementation begins for projects of non-trivial complexity, and design documents are reviewed by peers with the same rigor applied to code.

Stripe's approach to knowledge writing addresses the most common knowledge documentation failure -- documentation as afterthought, written when the project is complete and the writer has moved on -- by making documentation simultaneous with development. The knowledge is captured while it is freshest, by the people who understand it most deeply, under organizational conditions that treat documentation as real work rather than administrative overhead.

References

Tags

knowledge-management writing expertise documentation work-skills

Frequently Asked Questions

What makes knowledge writing different from regular writing?

Knowledge writing differs from regular writing in its purpose and constraints. Regular writing communicates information you already know how to articulate—you understand the topic and organize thoughts for an audience. Knowledge writing, in contrast, involves extracting and structuring expertise that may be tacit, implicit, or difficult to articulate—the writer often doesn't fully understand what they know until they try to write it down. Knowledge writing serves as external memory and learning tool, not just communication, so it must be structured for retrieval and building understanding over time. It focuses on concepts, principles, and decision frameworks rather than specific instances or narratives. Knowledge writing is also iterative—you often can't write it completely in one session because articulating tacit knowledge requires reflection, revision, and testing whether your articulation actually captures the insight. The format matters more in knowledge writing: using consistent structures (problem-solution patterns, decision trees, frameworks) helps both capture and retrieve knowledge effectively. Knowledge writing often includes meta-information like context (when this applies), limitations (when this doesn't work), and reasoning (why this matters), not just the fact itself. It's designed for future reference by people who need to understand or apply the knowledge, which means including examples, counterexamples, and common misunderstandings. The test of good knowledge writing isn't whether it sounds good but whether someone can read it and actually use the knowledge—does it transfer expertise, not just information?

How do you capture tacit knowledge that experts have but struggle to articulate?

Capturing tacit knowledge—the expertise that people demonstrate but can't easily explain—requires specific techniques beyond just asking 'what do you know?' Most effective is the 'explain your thinking' approach: have experts talk through their process while solving a real problem or reviewing actual work, narrating their decisions as they make them ('I'm checking X first because Y often indicates Z'). Record these sessions and transcribe them, then distill patterns from how they approach problems. Use the 'contrast cases' method: show experts pairs of examples (one good, one problematic) and ask what differences they notice—experts can often articulate criteria through comparison even when they can't define standards abstractly. The 'novice questions' technique involves having someone unfamiliar with the domain ask basic questions that force experts to unpack assumptions ('Why do you always check that first?' 'How do you know when to escalate?'). Interview about specific incidents: 'Tell me about a time when you had to make a difficult technical decision' yields concrete stories that reveal decision-making principles. Build knowledge progressively through iteration: write an initial draft based on interviews, have the expert review and refine, then test it with novices to see what's missing. Look for phrases like 'you just know' or 'it's intuition'—these mark tacit knowledge that needs unpacking. Ask 'what would a junior person miss?' or 'what mistakes do newcomers make?'—experts can often articulate what not to do even when they can't explain what to do. The goal is externalizing mental models, heuristics, and pattern recognition that experts apply unconsciously.

What structures and formats work best for different types of knowledge?

Different knowledge types benefit from specific structures that match how that knowledge is used. For procedural knowledge (how to do something), use step-by-step instructions with prerequisites, expected outcomes, and common errors at each step—numbered lists work well because they're sequential and checkable. For conceptual knowledge (understanding how something works), use explanatory structures with definitions, examples, analogies, and diagrams showing relationships—hierarchical outlines or concept maps work well. For decision-making knowledge, use decision trees, criteria matrices, or if-then flowcharts that encode how experts choose between options. For troubleshooting knowledge, use symptom-diagnosis-solution formats organized by what the person observes first. For strategic knowledge (when to apply different approaches), use case-based formats showing scenarios, context, and outcomes—'use X when..., but Y when...' structures. For reference knowledge (facts and specifications), use tables, lists, or glossaries optimized for lookup rather than learning. For principle-based knowledge (underlying laws or patterns), use problem-solution pairs showing the principle in action across different contexts. For design knowledge (tradeoffs and patterns), use pattern catalogs with context, problem, solution, and consequences clearly separated. Templates work well for knowledge that involves filling in standard structures (project planning, incident reports). Checklists work for knowledge that involves verification (deployment steps, security review). The key is matching structure to use: procedural knowledge gets referenced while doing, so it needs to be scannable; conceptual knowledge gets read to build understanding, so it can be more narrative. Multiple formats for the same knowledge serve different needs—a concept might need both a reference definition and a tutorial-style explanation.

How do you organize personal knowledge systems that grow over time?

Organizing personal knowledge systems for growth requires structures that don't break as content accumulates and that support both storage and retrieval. Most effective is a multi-layered approach using both hierarchical organization (folders/categories for browsing) and non-hierarchical connections (tags, links for navigation). Start with a simple top-level structure based on how you actually use knowledge: areas of responsibility, projects, resources, and archives (the PARA method) or by knowledge domains (work, learning, personal). Keep the top level simple—3-8 categories maximum—because deep hierarchies become unmaintainable. Use consistent naming conventions that make content discoverable through search: descriptive titles that include key terms, dates in consistent format (YYYY-MM-DD), and clear metadata. Implement progressive summarization: capture information in full initially, then highlight key points, then distill summaries, then extract insights—this creates layers that help future retrieval. Build connection systems through heavy internal linking: when writing about concept A that relates to concept B, link them—this creates a knowledge graph over time. Use tags for cross-cutting themes that don't fit hierarchies (like 'decision frameworks' or 'common mistakes'). Create index notes or maps of content that collect links to related material by theme. Review and refactor regularly: quarterly reviews to consolidate redundant notes, archive completed projects, and improve organization based on actual usage patterns. Avoid premature organization—when starting, accept some messiness and let categories emerge from actual use rather than trying to design the perfect system upfront. The goal is a system that's easy to add to (low friction for capture) and easy to retrieve from (multiple access paths), not one that's perfectly organized but becomes a chore to maintain.

What are common mistakes when writing documentation meant to transfer knowledge?

Common knowledge transfer mistakes include writing from expert perspective without scaffolding, focusing on what rather than why, and treating knowledge as static rather than contextual. Writing from expert perspective means assuming readers have background knowledge they don't, using terminology without definition, skipping steps that seem obvious, and organizing by logical structure rather than learning sequence. Novices need progressive disclosure—start simple, build complexity gradually—but experts often present complete complexity at once because that's how they think about it now. Focusing on what without why means providing facts, procedures, or specifications without explaining rationale, tradeoffs, or conditions where they apply. 'Do X' is less transferable than 'Do X because Y; in cases where Z, do W instead.' The why helps readers adapt knowledge to new situations rather than just following recipes. Treating knowledge as static means presenting information without context about when it's applicable, what assumptions underlie it, or how it might need to adapt. Document what you know, but also document conditions, exceptions, and boundaries. Other major mistakes include organizing knowledge for writing convenience rather than reader discovery, writing once without iteration to test whether knowledge actually transfers, providing only abstract explanations without concrete examples (or only examples without generalizable principles), and missing the curse of knowledge—failing to recognize what's unclear because you can't remember not knowing it. Poor knowledge writing also tends to be context-free ('use this tool') without explaining the problem it solves or alternatives, making it hard to know when to apply. The test is whether someone reading your documentation can not just follow instructions but understand enough to adapt and make good decisions in novel situations—that's genuine knowledge transfer, not just information transmission.

Share this article