Define the problem

Age alone does not create debt; user failure and maintenance cost do. A page becomes debt when it creates a measurable wrong turn: a failed task, a support ticket, an unsafe workaround or recurring editorial rework.

Choose a useful model

Start with support questions, failed searches and emergency corrections instead of a list of old files. A useful triage board scores impact and confidence separately, so an obviously stale but rarely visited page does not outrank a small page that breaks a common task.

Build the workflow

Classify accuracy, findability, ownership, duplication and structural problems before choosing a fix. Fix the highest-risk class first: correctness before findability, findability before polish, and ownership before broad rewrites that nobody can maintain.

Check the result

Pay debt in small release-sized pieces so normal publishing does not stop. After each repair, check whether the triggering signal changes; if support questions stay flat, the team may have fixed the wrong symptom.

Keep it maintainable

Keep the debt register small: user task, problem type, owner, impact and next action. The register should be a decision queue, not an archaeological catalogue of everything old in the repository.

Applied example

To make the ideas in “Documentation debt: how to find what is actually hurting users” operational, take one piece of documentation that is actually changing this week: a procedure, release page, onboarding step, troubleshooting article or ownership record. Make a working copy and write down four things before editing it: who uses it, what event makes it change, who can verify the facts, and what the reader should be able to do when finished. That small inventory exposes hidden assumptions faster than a general “improve the docs” task.

Run one realistic change through the workflow from start to finish. Do not redesign the whole system. Change one fact, one step or one responsibility and observe where the process slows down or loses information. A useful review asks:

  • Can the reader identify the expected outcome without asking the author?
  • Is there a clear owner for the next update?
  • Can a reviewer verify the changed fact from the product or process itself?
  • Does the page still make sense if an old screenshot, note or workaround is removed?

The point is to test the method under a real maintenance event. Documentation practices become trustworthy when they survive change, not when they look tidy in a static example.

Quick editorial checklist

  • Define the problem. Age alone does not create debt; user failure and maintenance cost do.
  • Choose a useful model. Start with support questions, failed searches and emergency corrections instead of a list of old files.
  • Build the workflow. Classify accuracy, findability, ownership, duplication and structural problems before choosing a fix.
  • Check the result. Pay debt in small release-sized pieces so normal publishing does not stop.