The Wiki That Should Have Worked
Marcus joined a 180-person SaaS company as its first dedicated people ops lead in the spring. He had done this kind of work before: audit the existing processes, fill the gaps, build something people would actually use. He came in expecting to find the usual mess. What he found instead surprised him.
The documentation existed. There was a wiki. There were onboarding guides, process pages, policy documents, how-to articles for the most common employee questions. Whoever had built it had done a reasonable job. The structure made sense. The pages were organized. By any surface-level measure, the company had solved its process documentation problem.
And yet in his first two weeks, Marcus watched the same thing happen over and over. An employee would have a question: how does PTO carry over, what is the process for requesting a new software license, who approves exceptions to the travel policy. The employee would not check the wiki. They would ping someone in Slack. Usually they pinged their manager, or the person who had been there longest, or Marcus himself.
He assumed the problem was awareness. People did not know the wiki existed, or did not know where to look. He added links. He pointed people toward the right pages in their onboarding sessions. He mentioned the wiki in team meetings. The pings kept coming.
What Marcus did not yet understand was that the employees were not uninformed. They had learned, through experience, that the wiki was not reliable. Some pages were accurate. Some were outdated. And there was no way to tell the difference without verifying with a human anyway. The rational response was to skip the wiki and go straight to the human.
He decided the problem was process documentation quality. He was going to fix it properly this time.
How to Document a Process That People Will Actually Use
Process documentation is a written record of how a task or workflow is performed, including the steps, decisions, and context required to repeat it reliably. When it works, a process documented once answers the same question hundreds of times, at no cost to the person who first knew the answer. Marcus understood this. He had built process documentation before. He spent the next six weeks rebuilding it from the ground up, more deliberately than most organizations attempt, and the approach is worth working through in detail, because the steps most people skip are the ones that determine whether the documentation actually gets used.
Choose the format for the knowledge type, not the audience
The first mistake most process documentation efforts make is choosing a single format for everything. A step-by-step numbered list works well for a linear process with a defined sequence: how to submit an expense report, how to provision a new user account, how to file a support ticket. It works poorly for processes that require judgment: how to handle a performance conversation, how to evaluate a vendor, how to prioritize competing requests from different stakeholders.
Marcus learned to distinguish between three types of process knowledge before choosing a format. Linear processes with clear steps belonged in numbered lists. Decision-based processes with multiple paths belonged in flowcharts or decision trees, which made the branching logic visible in a way that prose never could. Judgment-based processes, where the right answer depended on context that no template could anticipate, belonged in annotated case examples: here is a situation, here is how it was handled, here is the reasoning behind that decision.
Matching format to knowledge type sounds obvious. Most organizations do not do it, because it requires the person building the documentation to think carefully about what kind of knowledge they are actually capturing rather than defaulting to the format they are most comfortable writing. Once the format is right, the next question is what to put inside it, and this is where most documentation efforts lose the most value.
Capture the context behind the steps, not just the steps
The most common reason process documentation fails to help the person reading it is that it describes what to do without explaining why. The steps are correct. The context that makes the steps work in edge cases is missing.
Marcus found this pattern throughout the existing documentation. The PTO policy page accurately described the accrual and carry-over rules. It did not explain that the system did not auto-update until the first of the following month, which meant that an employee checking their balance on December 31st would see the wrong number. That detail had been explained in Slack dozens of times. It appeared nowhere in writing.
For each process he rebuilt, Marcus added a context layer beneath the steps: why this step exists, what happens if it is skipped, what the common mistakes are and how to recognize them, and what to do when the documented path does not apply. This is the part of process documentation that takes the most time and produces the most value. It is also the part that most people omit, because it requires reconstructing not just the process but the accumulated understanding behind it.
Get input from the person doing the work, not the manager above it
Process documentation built from a manager's understanding of how something works is almost always incomplete in the same direction: it describes the intended process, not the actual one. The person doing the work knows where the steps diverge from the documentation, which workarounds have become standard practice, and which parts of the written process were abandoned after the first month because they did not reflect how the work actually gets done.
Marcus built a simple protocol: before documenting any process, he interviewed the person who performed it most frequently. Not their manager. Not the person who had designed it. The person doing the work on a Tuesday afternoon. He asked three questions: what does this process look like when it goes smoothly, what does it look like when it does not, and what do you do that is not written down anywhere.
The third question was consistently the most valuable. It surfaced the knowledge that had never been captured: the timing quirks, the vendor contacts, the judgment calls that had calcified into unofficial standard practice. Without those answers, even a carefully written process document was missing its most useful content. Getting that content into the document is only half the job; the other half is verifying that it actually works for someone who was not in the room when it was written.
Test the document before you publish it
A process document that has not been tested is a hypothesis, not documentation. The test is simple: give the document to someone who has never performed the process and ask them to complete it using only what is written. Watch where they hesitate. Note where they ask questions. Every hesitation and every question is a gap in the documentation.
Marcus ran this test on every process he rebuilt. The results were humbling. Documents that he considered thorough produced hesitations he had not anticipated, because the context that felt obvious to him was not available to the reader. The test consistently surfaced two to three gaps per document that revision alone would never have caught.
The testing step adds time. It also dramatically increases the probability that the documentation will function as intended rather than sitting unused in the wiki because nobody found it reliable enough to trust.
Why Process Documentation Decays Even When You Build It Right
Six months after Marcus finished rebuilding the documentation, the Slack pings had decreased. The onboarding experience had improved. New hires were finding answers without scheduling calls. The wiki was being used. His manager mentioned it in a team meeting as an example of what good ops work looked like. By the metrics he had set out to improve, the project was a success.
Then things started quietly going wrong.
The company switched payroll providers. The expense reimbursement process changed. Two teams reorganized and the approval chains in several process documents no longer reflected reality. Nobody updated the wiki, because updating the wiki was not anyone's job in the way that every other task was someone's job. The documentation that had been accurate in March was becoming misleading by September, and it was doing so silently, with no indication to the reader that anything had changed.
This is the fundamental problem with process documentation maintenance: the organizations that need it most are the ones changing fast enough to make it decay quickly. Every process update, tool migration, team reorganization, and policy change makes some percentage of the existing documentation quietly wrong. McKinsey research on knowledge work finds that employees spend approximately 20% of their working week searching for information or tracking down the right colleague to ask. A large portion of that time is spent compensating for documentation that exists but cannot be trusted.
The employees who could keep documentation current are precisely the ones who have no time to do it. The feedback loop on documentation quality is so delayed and indirect that it barely registers as a priority. A process document goes stale in October. The person who discovers it is wrong sends a Slack ping in November. The person who receives the ping updates the document in December, if they remember. In the meantime, everyone who consulted that document in October and November received bad information and probably acted on it. This is the decay cycle that most internal wikis cannot escape, a pattern covered in the post on why your wiki becomes a graveyard.
The Knowledge That Won’t Fit in Any Document
While Marcus was watching the decay problem develop, he was also running into a second problem that his documentation approach could not solve, no matter how carefully he built the documents.
Some of the knowledge he was trying to capture resisted documentation entirely.
The head of engineering had been at the company since the early days. He carried a detailed mental map of why systems had been built the way they were, and he knew things that did not appear anywhere in the codebase: that a particular config file which looked redundant was the only thing preventing a specific failure mode that had appeared twice in production, and that a workaround buried in a deployment script had been added after a 2 a.m. incident that nobody had written up. Marcus interviewed him for three hours. He produced a document that was thorough, well-organized, and missing the most important parts.
Psychologists call this the curse of knowledge: once you understand something deeply, it becomes very hard to remember what it was like not to know it. The head of engineering could not fully document what he knew because he could not fully see it. The knowledge that felt most obvious to him was the knowledge he did not think to include, including the name of the vendor contact who actually picked up the phone when something went wrong.
This is the tacit knowledge problem: the practical wisdom built through years of doing a specific job in a specific organization, which cannot be fully articulated even by the person who holds it. It surfaces naturally in Slack, when someone asks a question and the expert answers with full context intact. It almost never surfaces in a documentation session, because the expert does not know what they know until someone asks the right question. As the series post on why experienced employees don’t document their insights covers in detail, the documentation gap is not a motivation problem. It is a structural mismatch between what documentation asks of experts and what experts are actually able to give.
Marcus could build excellent process documentation for the linear, explicit processes: onboarding steps, expense workflows, policy references. For the deeper, contextual knowledge that the organization actually ran on, documentation was an incomplete solution at best.
The Orphan Problem
Eleven months into Marcus's tenure, the ops lead who had built most of the original process infrastructure moved to a new role at a different company. She had been the de facto owner of roughly a third of the documentation in the wiki: the processes she had designed, the pages she had written, the institutional context she carried for why certain decisions had been made the way they were.
Her pages did not disappear when she left. They remained in the wiki, looking exactly as they had the day she wrote them, with no indication that the person who understood them well enough to update them was gone. They became what Marcus would later call orphaned documentation: pages that existed, that appeared findable and credible, but that had no one left to maintain them or to answer questions about what they meant.
The orphan problem is distinct from the decay problem, though it accelerates it. Documentation decays when the organization changes and nobody updates the pages. Documentation becomes orphaned when the person who built it and understood it deeply enough to maintain it is no longer there. Orphaned documentation decays faster, because there is no one positioned to catch the errors, and it misleads more confidently, because it still carries the authority of the person who wrote it.
The financial cost of this kind of knowledge loss is real and specific. Research from Panopto finds that 42% of role-specific expertise is known only by the person currently doing that job. When that person leaves, a new hire typically spends close to 200 hours working inefficiently, re-asking questions that were already answered, and rediscovering things the team already knew. UC Irvine research on interruption costs finds it takes an average of 23 minutes to fully regain focus after a single interruption: every time that new hire has to ask a colleague for an answer that orphaned documentation should have provided, someone loses nearly half an hour of focused work. The post on what companies lose when employees leave covers the compounding cost of this cycle. Orphaned documentation does not prevent that loss. It creates a false floor: the appearance of preserved knowledge that breaks the moment someone tries to stand on it.
Marcus now had two problems compounding each other. Process documentation that was technically built well was decaying because no one had time to maintain it. And the documentation that had an implicit owner was becoming orphaned as people moved on. The wiki was beginning to look, again, like the wiki he had inherited.
What Marcus Eventually Understood
Marcus had spent almost a year trying to solve a process documentation problem with better process documentation. He had improved the quality substantially. He had reduced the Slack pings. He had built something meaningfully better than what he had inherited. And the fundamental problem was still there, still compounding, still producing the same failures on a slightly longer timeline.
The realization that shifted his thinking was simple: the documentation model asks the wrong people to do extra work at the wrong time with no sustainable incentive to keep it current. The people who know the most are the ones with the least time to document. The documentation that gets created captures the explicit layer and misses the tacit one. And the moment the person who built a document leaves or changes roles, the document starts drifting from reality with no one positioned to catch it.
This is not a fixable problem within the documentation model. It is a property of the model itself. The research on this is direct: as covered in the post on why nobody uses your documentation, teams develop a rational heuristic of bypassing documentation entirely when they learn that it cannot be trusted. Every failed search reinforces that heuristic. The documentation that is accurate stops getting consulted because the team has no way to distinguish it from the documentation that is not.
What Marcus was looking for was not a better documentation process. It was a different model for preserving organizational knowledge: one that did not depend on experts setting aside time to write things down, did not require a designated maintainer to keep things current, and did not become orphaned when the person who understood it best moved on.
He started paying attention to where the knowledge he was trying to document was actually being shared. The answer was consistent: Slack. The head of engineering explained architecture decisions in Slack threads. The ops lead had walked colleagues through processes in Slack. Marcus himself had answered dozens of questions in Slack that had never made it into any document. The knowledge was being shared continuously. It was just disappearing into the archive as fast as it was created.
A Different Model for the Knowledge That Documentation Can’t Hold
The documentation model and the capture model solve different versions of the knowledge problem.
Process documentation is the right tool for explicit, stable, linear knowledge: the steps that do not change, the policies that apply uniformly, the workflows that can be codified and followed without judgment. Building that documentation well, as Marcus had learned, requires choosing the right format for the knowledge type, capturing context not just steps, sourcing from the person doing the work, and testing before publishing. That work is worth doing. It does not solve the tacit knowledge problem and it does not solve the orphan problem.
The capture model addresses what process documentation cannot. Rather than asking experts to set aside time to write down what they know, it captures the knowledge they are already sharing in the course of doing their work: the Slack thread where an engineer explains why a system was built a certain way, the channel discussion where an ops lead walks a colleague through a process, the response to the question that five people will ask again next quarter. That knowledge is captured, attributed to the person who shared it, and made permanently searchable, without requiring anything additional from the expert.
Attribution is the specific answer to the orphan problem. Documentation assigned to a maintainer becomes orphaned when the maintainer leaves. Knowledge attributed to a contributor does not become orphaned in the same way: it remains credited to the person who created it, searchable by anyone who needs it, and peer-validated by colleagues who found it useful. When the contributor leaves, their contributions persist. The organization retains what they knew, in the form they actually shared it, with the context that made it useful intact.
Pravodha is built around this capture model. It integrates with Slack to preserve the institutional knowledge your team generates every day: attributing it to the people who created it, surfacing peer validation through colleagues who recognize contributions as valuable, and making it permanently searchable without adding any burden to the experts who know the most. The result is a living knowledge base that updates itself as work happens, rather than a wiki that requires a dedicated maintenance effort that organizations can never sustain. If your team has already tried the documentation model and found it wanting, we would like to show you why the capture model works where documentation alone does not.