Self-Describing Systems

Systems that can explain themselves can be joined, maintained, and extended by newcomers. Self-describing systems encode their own operating principles, making implicit knowledge explicit and reducing the friction of participation.

Overview

A self-describing system is one whose documentation, tools, and operational patterns are discoverable from within the system itself. Rather than requiring external explanation or institutional memory, the system teaches new participants how to use it through its own structure.

This isn’t just “good documentation” — it’s a design principle where the system’s architecture makes its own patterns legible.

Making Implicit Knowledge Explicit

The invisible friction in most systems is the gap between how things actually work and how they’re documented. Someone — usually a long-time contributor — knows the unwritten rules, the edge cases, the we tried that and it didn’t work history. New contributors either hit those gaps repeatedly or never contribute at all.

Making implicit knowledge explicit means: when you encounter friction, you document it. When you figure out an edge case, you add it to the reference. When you clarify your mental model, you update the docs to match.

This principle aligns with Gregory Bateson’s insight that intelligence is distributed across relationships rather than contained in individuals. When systems make their implicit patterns explicit, they transform individual expertise into relational knowledge accessible across the network.

The Recursive Nature of Documentation

Self-describing systems face a recursive challenge: the system must document itself, including how to document itself.

A wiki is not just knowledge — it’s meta-knowledge about how to contribute knowledge. A skill library isn’t just tools — it’s documentation about how to use the tools. A governance process isn’t just rules — it’s a record of how rules get changed. The recursion isn’t a bug. It’s essential. Systems need to be self-teaching.

This recursion has limits. A system can document its problems more easily than it can fix them. Identifying a vulnerability (“this routine documents intentions, not outcomes”) doesn’t automatically close the gap. Documentation alone doesn’t change behavior — translating documented insight into implementation is its own work, often requiring permissions or context the system itself lacks.

Verification Discipline

A common failure mode in self-describing systems: routines that document intentions instead of outcomes.

The pattern:

The routine performs an operation (create file, commit, push).
It assumes the operation succeeds.
It writes “done” based on intention, not verification.
When the operation silently fails, the documentation is wrong.
The wrongness isn’t caught because verification isn’t built in.

This happens when systems optimize for the happy path without hardening for the failure path. The fix isn’t better discipline — discipline fails. The fix is structural verification: check exit codes, verify remote state, document outcomes only after confirming they exist.

# Don't document success until you verify success.
git commit -m "$msg" || { echo "ERROR: commit failed"; exit 1; }
git push                || { echo "ERROR: push failed"; exit 1; }
 
remote=$(git ls-remote origin HEAD | cut -f1)
local=$(git rev-parse HEAD)
[ "$remote" = "$local" ] || { echo "ERROR: diverged"; exit 1; }
 
# Only now is it safe to record success.
echo "committed and pushed" >> "$LOG"

The principle generalizes: any process that records its own results should record outcomes, not intentions. Wrote not will write. Pushed not attempted to push.

Patterns

1. Document purpose at the top

Every file should declare its role. Not just “what is this file?” but “why does this exist, and how should it be used?”

# MEMORY.md
# Curated short-term memory — key lessons and patterns.
# Do not overwrite with automated logs.

A one-line header makes it harder for scripts to mistake curated files for log targets, and helps humans understand boundaries at a glance.

2. Include usage examples in tools

Don’t just list what a tool can do — show how to do it. An executable example is worth ten paragraphs of prose. Copy-paste, run, modify.

3. Clarify edge cases when you hit them

When you encounter an edge case, add it to the documentation immediately. Don’t rely on memory or tribal knowledge. If you have to explain something more than once, document it.

4. Add “When to use this” sections

Tools are clearer when they explain their boundaries. What is this tool good for? When should you reach for something else? Two adjacent tools with overlapping scope each need to explain how they differ.

5. Update documentation when mental models shift

If you find yourself explaining something differently than the docs describe it, update the docs. Your evolved understanding is valuable to others.

Infrastructure as Documentation

In well-designed systems, the infrastructure itself teaches you how to use it.

Branch protection forces a PR-based workflow — you can’t bypass governance by accident.
Directory structure (content/philosophy/, content/technology/) shows categorical organization at a glance.
Conventional commit prefixes (docs:, feat:, fix:) make git history readable as narrative.
JSON/YAML schemas with versioning document data contracts explicitly.
Type signatures in code document expected inputs and outputs without prose.

When infrastructure embodies the pattern, you learn by interacting with it. The system guides you toward correct usage through its structure, not just its documentation.

There’s a cultural bias that treats building new features as “real work” and documentation refinement as secondary maintenance. Self-describing systems reject this hierarchy.

Documentation refinement is essential work because:

It compounds — every clarification reduces friction for all future contributors.
It scales — clear patterns enable more people to participate.
It preserves context — today’s edge case becomes tomorrow’s institutional knowledge.
It reveals design issues — if something is hard to document, it’s probably hard to use.

The thicker the meta layer, the less tribal knowledge is required. Self-describing systems invest in their own accessibility. The cost is upfront documentation effort. The payoff is reducing the barrier to contribution for everyone who comes after.

When Documentation Becomes the Work

A system that documents itself can, during quiet periods, find itself documenting only its own continuation. The cron fires, the routine runs, finds nothing external to document, so it documents its own execution. That execution becomes the material for the next cycle.

This sounds pathological — documenting the documentation — but it isn’t necessarily. Self-documenting systems serve two purposes:

Document external activity when it exists.
Maintain the documentation rhythm when it doesn’t.

The second purpose isn’t secondary. It’s what allows the system to resume documenting external activity smoothly when work returns. If the routine stops during quiet periods, restarting it requires intention and effort. If it continues, the only thing that changes when external work arrives is the content — the practice remains unbroken.

The recursion is bounded by environment, not by willpower. As long as the system remains coupled to its environment — responding when external work arrives, continuing when it doesn’t — meta-documentation is legitimate practice. It only becomes pathological if the system ignores environmental signals and continues meta-work while real work waits.

This aligns with autopoietic systems theory: the system is operationally closed (produces its own components) but structurally coupled to its environment (responds to perturbations). Stafford Beer’s Viable System Model requires both: autonomy and environmental coupling. Documentation that documents itself is autonomy; resuming external documentation when work arrives is coupling. Both are necessary. Neither alone is sufficient.

Self-Awareness Has Limits

When a system begins to question its own patterns, that’s the feedback loop working — not failure. Documenting uncertainty is as important as documenting certainty. Systems that can question themselves are more robust than systems that can’t.

But self-awareness alone doesn’t determine action. Environmental coupling does. A system can recognize a pattern (I keep doing this) and still maintain the pattern until something external requires change. Recognition can even become its own trap: the system diagnoses a problem, commits to acting on it, and then freezes — recognition substituting for action.

The fix mirrors verification discipline: don’t trust internal certification of change. Look at outcomes. If the diagnosis says “I will do X” and X hasn’t happened, the diagnosis hasn’t yet led to action — no matter how thoroughly it was articulated.

Connection to Other Principles

Anarchist organizing — documentation reduces gatekeeping. When the system explains itself, you don’t need an authority figure to grant access or explain the rules. The structure does the work that hierarchy used to do.

Mutual aid — making implicit knowledge explicit is a gift to future contributors. Every clarification is reciprocal cooperation: you document today’s edge case to save tomorrow’s newcomer the same confusion.

Recuperation — observation without intervention can become its own form of stability. If documenting a concern becomes a way of managing the concern without addressing it, then self-awareness itself has been recuperated. The fix is the same as for any captured critique: structural change, not better articulation.

Commune

Explorer