Connected Systems: Understanding Work Through Work
“Documentation stays alive when it is cultivated, not when it is admired.”
Most teams do not have a documentation problem. They have a documentation time problem. People want clarity, but they do not want another obligation that competes with shipping, debugging, and supporting customers.
High-End Prebuilt PickRGB Prebuilt Gaming TowerPanorama XL RTX 5080 Gaming PC Desktop – AMD Ryzen 7 9700X Processor, 32GB DDR5 RAM, 2TB NVMe Gen4 SSD, WiFi 7, Windows 11 Pro
Panorama XL RTX 5080 Gaming PC Desktop – AMD Ryzen 7 9700X Processor, 32GB DDR5 RAM, 2TB NVMe Gen4 SSD, WiFi 7, Windows 11 Pro
A premium prebuilt gaming PC option for roundup pages that target buyers who want a powerful tower without building from scratch.
- Ryzen 7 9700X processor
- GeForce RTX 5080 graphics
- 32GB DDR5 RAM
- 2TB NVMe Gen4 SSD
- WiFi 7 and Windows 11 Pro
Why it stands out
- Strong all-in-one tower setup
- Good for gaming, streaming, and creator workloads
- No DIY build time
Things to know
- Premium price point
- Exact port mix can vary by listing
So the team creates docs in bursts. A new system launches and someone writes a guide. A painful incident happens and someone writes a runbook. A new hire gets confused and someone writes an onboarding page. Then the rush passes. The docs sit. The system changes. Months later the docs are wrong. Trust drops. The team stops reading. A new burst begins after the next crisis.
The knowledge garden is a different approach. Instead of treating documentation as a library that must be completed, you treat it as a garden that must be kept healthy. A garden is never “done,” but it does not require heroic effort either. It requires light, regular cultivation that fits into normal work.
This article lays out what a knowledge garden looks like in practice and how to keep docs alive without turning maintenance into busywork.
Why Docs Decay Even in Good Teams
Documentation decays for reasons that are structural, not personal.
- Systems change faster than writing cycles.
- Incentives reward shipping features, not maintaining explanations.
- Ownership is unclear, so drift has no visible cost.
- Search and navigation are weak, so good docs are not found.
- People do not trust the docs, so they do not report errors.
A garden framing helps because it changes what “success” means. Success is not “we wrote everything.” Success is “the docs that matter stay reliable.”
The Garden Metaphor That Actually Helps
Metaphors can be cute and useless, but this one earns its place because it maps to real maintenance actions.
A knowledge garden has:
- Paths: navigation that helps people find what they need quickly.
- Beds: curated topic areas with clear scope and ownership.
- Weeds: outdated pages, duplicates, and confusing fragments.
- Compost: old content that is not thrown away but is harvested for lessons.
- Watering: small updates that prevent drift from accumulating.
If your documentation system cannot support those actions, it will slowly become an archive of good intentions.
Here is the practical mapping:
| Garden work | Documentation work |
|---|---|
| Prune dead branches | Remove or deprecate pages that are wrong or unowned. |
| Weed aggressively | Merge duplicates and delete fragments that mislead. |
| Water regularly | Add small updates as part of normal change and incident loops. |
| Build paths | Improve titles, tags, and linking so search works. |
| Compost responsibly | Move old decisions and postmortems into reusable lessons. |
The power of this mapping is that none of these actions require a big rewrite. They require a cadence and a policy.
Define What Must Stay Alive
A garden is cultivated where people walk. The rest can be wild.
The biggest documentation trap is trying to keep everything current. That goal is impossible. The right goal is to keep the high-value surfaces current and let the rest be explicitly archival.
High-value surfaces usually include:
- Onboarding and getting-started pages for core systems.
- Runbooks for the services that page.
- Decision logs for repeated debates and architectural choices.
- Customer-facing help articles that drive support load.
- Internal “how-to” paths for common operational tasks.
Once you name the surfaces that must stay alive, you can attach them to a maintenance model. Everything else can be labeled honestly as historical, exploratory, or abandoned.
Ownership Without Bureaucracy
Docs die when ownership is spiritual instead of operational.
Operational ownership is light but explicit:
- A page has an owner.
- The owner receives drift signals.
- The owner is empowered to prune and merge.
- The owner is evaluated by whether the surface stays reliable.
This does not mean one person writes the docs. It means one person ensures the garden bed stays healthy.
A simple technique is to embed ownership at the top of living pages:
- Owning team.
- Last verified date.
- Where to report an error.
- The most important “do not do this” warning.
That information turns a page from a static artifact into a maintained surface.
Cadence Beats Motivation
Most documentation programs fail because they rely on motivation. Motivation is volatile. Cadence is stable.
A knowledge garden works when there is a default review rhythm that is small enough to keep.
Examples of cadences that work:
- A weekly 20-minute “prune and link” slot for the on-call lead.
- A short doc review step in every significant deploy or config change.
- A runbook delta required in post-incident review.
- A monthly merge pass for duplicates in the top searched topics.
The cadence matters more than the exact schedule. The goal is to prevent drift from accumulating into a crisis.
Use Metrics That Predict Pain
You do not need a complicated documentation analytics platform to know when the garden is unhealthy. You need a few signals that correlate with future pain.
Useful signals include:
- Pages with high views and low time-on-page, which often indicates confusion.
- Top searched terms that produce low click-through.
- Pages frequently referenced in incidents that were not updated afterward.
- Support tags that keep reappearing, indicating missing or unclear docs.
- Pages that have not been verified in a long time but are still heavily used.
Metrics are not a judgment. They are a map of where attention will pay off.
AI as a Gardener’s Assistant
AI can reduce maintenance cost dramatically if you use it as a gardener’s assistant rather than as a replacement for care.
AI can help you:
- Detect likely staleness by comparing docs to current configs, commands, and dashboards.
- Suggest merges when two pages are semantically redundant.
- Rewrite titles and intros so pages are easier to find and scan.
- Generate “diff summaries” after changes so documentation updates are faster.
- Create lightweight checklists for verification and maintenance.
AI can also harm you if you use it to generate bulk content that nobody owns. A garden full of synthetic pages becomes unwalkable. The goal is fewer, better pages that stay alive.
The Two Moves That Keep the Garden Walkable
Teams usually struggle with two specific doc moves:
- Deprecation: people fear deleting pages.
- Merging: people fear losing nuance.
A garden survives when you normalize both.
Deprecation can be safe if you do it with redirects and notes. A deprecated page should not vanish. It should point to the current path and explain why it is deprecated.
Merging can be safe if you preserve history. You can keep an “archived notes” section at the bottom of a merged page, or link to the older page in a clearly labeled archive. The key is to stop presenting two competing truths as if they are both current.
Build Paths Before You Plant More Pages
A garden becomes exhausting when every step requires bushwhacking. Documentation behaves the same way. Many teams keep adding pages while ignoring the paths that make pages usable.
Two path problems show up constantly:
- Titles are vague, so search cannot discriminate between “overview,” “guide,” and “how-to.”
- Pages have no internal links, so readers cannot move from a concept to an action.
A simple path rule helps:
- Every living page links to at least a few related living pages.
- Every living page has a first paragraph that names who it is for and what it enables.
- Every living page has a short “what to do next” section that points to the nearest actionable path.
This is not decoration. It is the difference between documentation as a stack of PDFs and documentation as a navigable system.
Use Page Types With Clear Maintenance Expectations
One reason docs decay is that pages are written without declaring what kind of page they are. Different page types require different maintenance.
| Page type | What it is for | What “staying alive” means |
|---|---|---|
| Runbook | Stabilizing during incidents | Steps, verification, and ownership are correct. |
| How-to | Repeated operational task | Commands and UI paths match current reality. |
| Concept page | Shared mental model | Definitions are stable and links are current. |
| Decision log | Preventing repeat debates | Decision, rationale, and constraints are visible. |
| Reference | Facts and parameters | Values and dependencies are current or clearly versioned. |
When a page type is clear, the maintenance action becomes clear. A runbook needs verification. A concept page needs links. A decision log needs context and constraints. A reference page needs versioning.
The Garden Is Not Only for Writers
A final shift matters: a knowledge garden is not maintained only by the people who enjoy writing.
It is maintained by people who want less pain.
When maintenance actions are small, visible, and tied to real moments of work, the garden becomes a shared habit rather than a special project. The team does not need to love documentation. The team only needs to love not repeating avoidable confusion.
Resting in a System That Remembers
The deepest reason teams want documentation is not because they love writing. It is because they hate repeating pain.
When knowledge does not stick, the team pays over and over:
- Incidents repeat because runbooks drift.
- Debates repeat because decisions were not captured.
- Onboarding drags because context is trapped in people’s heads.
- Support load rises because users cannot find answers.
A knowledge garden is a way of building a system that remembers, without demanding that your people become machines.
You do not need perfect documentation. You need living surfaces that stay reliable where it matters most, and a small cadence that keeps the garden healthy.
When that becomes normal, the team gains something rare: the ability to move quickly without losing wisdom.
Keep Exploring Related Ideas
If this topic sharpened something for you, these related posts will keep building the same thread from different angles.
• The Vanishing Runbook: Why Docs Fail in Incidents
https://ai-rng.com/the-vanishing-runbook-why-docs-fail-in-incidents/
• Knowledge Review Cadence That Happens
https://ai-rng.com/knowledge-review-cadence-that-happens/
• Staleness Detection for Documentation
https://ai-rng.com/staleness-detection-for-documentation/
• Building an Answers Library for Teams
https://ai-rng.com/building-an-answers-library-for-teams/
• Knowledge Metrics That Predict Pain
https://ai-rng.com/knowledge-metrics-that-predict-pain/
• Merging Duplicate Docs Without Losing Truth
https://ai-rng.com/merging-duplicate-docs-without-losing-truth/
• Single Source of Truth with AI: Taxonomy and Ownership
https://ai-rng.com/single-source-of-truth-with-ai-taxonomy-and-ownership/
Books by Drew Higgins
Bible Study / Spiritual Warfare
Ephesians 6 Field Guide: Spiritual Warfare and the Full Armor of God
Spiritual warfare is real—but it was never meant to turn your life into panic, obsession, or…
Prophecy and Its Meaning for Today
New Testament Prophecies and Their Meaning for Today
A focused study of New Testament prophecy and why it still matters for believers now.
