I’ve onboarded at companies where the wiki was three years stale, the runbooks were wrong, and the only way to learn how things worked was to interrupt the person who built it. Every time, someone would say “we should really update the docs.” Nobody ever did, because documentation was a separate task from the actual work. That’s the fundamental design flaw.

At Zendesk, support teams handled the same questions repeatedly while product teams built features without checking the knowledge base. The information existed. It was scattered across Slack threads, wikis, and people’s heads. The problem wasn’t “write better docs.” The problem was that documentation happened in a separate workflow from the work itself.

Making documentation inseparable from the work

Knowledge-Centered Service (KCS) inverts the normal approach. Instead of documenting after the fact, you create and update documentation as a byproduct of solving problems. Not later. Not in a separate task. In the same motion. The methodology was developed by the Consortium for Service Innovation and originally designed for support organisations, but the principles apply everywhere a team creates and reuses knowledge.

Two loops drive it:

The Solve Loop. When you solve a problem, you document it right then. If an article already exists, you improve it. If it doesn’t, you create one. Every interaction is an opportunity to capture or refine knowledge.

The Evolve Loop. Over time, you look at patterns. Which articles get reused most? Which ones are outdated? Where are the gaps? This feeds back into process improvements, product changes, and training.

What this looks like in every project I run

In every project I touch now, Meitheal, Coolock Village Forge, this personal site, I follow one rule: if the behaviour changes, the docs change in the same commit. Not because I’m disciplined about it, but because the system is designed to make it the path of least resistance.

  • Knowledge is a product surface. Help text, setting descriptions, error messages, onboarding flows, and API docs are features, not afterthoughts. They get the same design attention as the UI.
  • Document as you go. Every architectural decision, workaround, and gotcha gets captured inline: code comments, README updates, ADRs, commit messages. Future-me is the first user of every doc I write.
  • Self-service by default. If someone has to ask a question that the docs could answer, the docs failed. Fix the docs, not the person.
  • Evolve continuously. When a bug is fixed or behaviour changes, all related documentation updates ship in the same changeset. Stale docs are worse than no docs because they teach the wrong thing confidently.

The principles that actually stick

PrincipleWhat It Means in Practice
AbundanceShare everything by default. Hoard nothing.
Create valueAn article that saves one person 10 minutes has already paid for itself.
Demand-drivenDon’t document things nobody asks about. Let real questions drive content.
TrustLet contributors update articles directly. Review later, not before.

When the overhead isn’t worth it

KCS adds overhead that isn’t worth it for throwaway prototypes or exploratory spikes. If the code will be deleted next week, don’t write a runbook for it. But for anything that will be maintained, even by future-you in three months, the 30 seconds to document now saves 30 minutes of archaeology later.

The teams that ship fastest aren’t the ones that write the most code. They’re the ones where anyone can pick up any piece of the system and understand it without asking. Documentation is how you get there, and the only way it stays current is if it’s inseparable from the work itself.

Want to discuss how I implement KCS practices in product teams? Get in touch.

Further Reading