Living doc

June 2, 2025
June 2, 2025

What makes a doc living isn’t the proclamation—it’s the practice. The quiet systems and small acts of care that keep it alive.

There’s always a bit of fanfare when a doc begins with:

“This is a living document.”

It sounds thoughtful. Inclusive. Alive. Usually met with nods: “About time someone wrote this down.”

But then what?

Most “living documents” die. Not with drama—just decay. Most are dead on arrival.

Because what makes a doc living isn’t the proclamation. It’s the practice. It’s not the label, but the labour. The systems. The caretaking.

That means:

That’s the work. That’s the system. And most of the time, that system… is just people. People noticing. And doing something about it.

Outdated

Docs go out of date. That’s not a flaw.

(It’s also not a reason to avoid writing things down.)

It just… is.

A doc is a snapshot. A moment in time, captured. Things change. Docs don’t—unless someone changes them.

So instead of punishing ourselves for the drift, we build a rhythm for revival. For upkeep.

Updating

Keeping a doc alive doesn’t require a heroic rewrite. It’s usually much simpler than that. It’s like noticing something’s off—and doing something small about it.

Like:

You notice because you’re in it. You’re in the grocery store—and spot the soup can in the middle of the aisle. You’re trying to stand something up: an API, a library, a service.

You find a doc, follow the steps… and hit a wall. Something’s changed. The doc is wrong. So you dig. Check Slack. Ask ChatGPT. Scan the official docs. Eventually, you figure it out.

Now what? Update the doc you found.

If you can’t edit it, that’s fine. Leave a comment. Post the fix where others can find it. Not just “this is wrong”—but here’s what’s right.

Update the doc. Put the can back on the shelf. And on going.

Responsibility

Is it everyone’s responsibility?

Yes.

But what about that saying—“If it’s everyone’s job, it’s no one’s”?

Sure.

Or maybe that’s just something we tell ourselves.

A story we use to justify inaction—because we’re unsure, or uncomfortable, or feel like it’s not our place to update a doc we didn’t write.

And there lies the real issue.

The problem isn’t that responsibility is distributed. It’s that care gets diluted—by nervousness, uncertainty, or just the everyday busyness of work.

Yes, every doc should have an owner—an individual or a team. But that doesn’t mean others can’t step in while the owners are busy.

Tend to the garden. Keep the thing going.

You don’t need to save the world. Just update the screenshot. Put the can back on the shelf.

And keep shopping.

Quiet work

As you walk the aisles of your (metaphorical) document grocery store, you start to notice a few things.

Some aisles are well-worn—scuffed floors from constant foot traffic leading to popular items. Patina. Other shelves? Covered in dust. Expired… 2020?! Yikes. Definitely out of date.

A half-written brain dump. Two sections still marked “TBD.” No one’s touched it in five years. Maybe it’s time to let it go.

What makes a doc living isn’t the loud opener. It’s the quiet work of the people who keep it alive—or retire it when it’s no longer useful. Not because it failed, but because it fulfilled its purpose.

As long as there are systems in place— the awareness to notice, the autonomy to act— the doc will keep on living. Because the things that stay alive—docs, tools, rituals, teams— aren’t self-sustaining. They’re sustained. They’re cared for.

No ceremony required. No need to announce that it was alive at all.

Filed under:

Got posts via newsletter