Documentation Is a Feature

Foundational Truth

Documentation is not administrative overhead.

It is not the final box to check after the real work is complete.

It is part of the solution.

If the work is not documented, the work is not finished.

A system without documentation may function today.

That does not mean it can be understood tomorrow.

---

What We Forget

I have worked in information technology for more than twenty years, and I still have text files saved in the cloud from 1999.

Some of them document solutions I developed during Y2K.

The technology has changed.

The systems have changed.

The people have changed.

But the value of the documentation remains.

I have forgotten more than most people will ever know in this industry.

That is not arrogance.

It is the natural consequence of time, complexity, and a career spent solving thousands of problems.

Human memory is not a reliable knowledge-management platform.

Documentation preserves what experience eventually erases.

---

The Two-Paragraph README

I routinely see engineers build enormous solutions.

They ask me to help test them.

We work through design problems, edge cases, failures, and recovery paths.

Then I ask a simple question:

"Where is the documentation?"

Sometimes they point to a two-paragraph README.

Sometimes they point to scattered comments in the code.

Sometimes they look at me as though I just ruined their first date.

The assumption is that the solution itself is the accomplishment.

It is not.

A solution that only its creator understands is not complete.

It is a dependency disguised as an achievement.

---

Documentation Is Part of the Product

A feature is not complete merely because it works.

It must be understandable.

Supportable.

Recoverable.

Transferable.

Auditable.

Repeatable.

Documentation is what makes those qualities possible.

The code may tell you what the system does.

It rarely tells you why it was built that way.

It does not reliably explain what alternatives were rejected.

It does not capture the incident that forced the design.

It does not preserve the operational knowledge required at two in the morning when the original engineer is unavailable.

Code explains behavior. Documentation preserves intent.

---

You Should Get Credit for the Recovery

Imagine that you spent three days without sleep overseeing the rollback of a change that took down the eastern seaboard.

You diagnosed the failure.

You coordinated the recovery.

You restored service.

You prevented further damage.

That work matters.

You should receive credit for it.

But if you did not document it, the work is only partially complete.

The organization may remember the recovery for a few weeks.

The people involved may remember it for a few years.

Eventually, the details disappear.

When they disappear, the organization loses the value of the lesson.

The incident becomes pain without progress.

---

The Thirty-Forty-Thirty Rule

For a major incident or complex change, I think of the work in three parts:

Thirty Percent: What Happened

Document the event.

What changed?

What failed?

When did it begin?

What systems were affected?

What symptoms were observed?

What decisions were made?

This creates the factual record.

Forty Percent: How We Recovered

Document the recovery in enough detail that another qualified person could repeat it.

What stopped the damage?

What restored service?

What commands were run?

What dependencies mattered?

What temporary measures were used?

What verification proved the environment was healthy?

Recovery documentation is often the most operationally valuable part of the entire event.

Thirty Percent: Cause of Event

Every significant incident should end with a formal Cause of Event.

Not a blame document.

Not a political exercise.

Not a collection of vague statements.

A Cause of Event should explain:

• what actually failed
• why safeguards did not prevent it
• why detection did not occur sooner
• what made recovery difficult
• what must change to prevent recurrence

An incident is not closed when service is restored. It is closed when the organization understands what happened and has acted on what it learned.

---

Recover in Minutes, Not Days

Good documentation changes the next incident.

Without it, teams rediscover the problem from the beginning.

They repeat old tests.

They search old logs.

They contact former employees.

They argue over incomplete memories.

They lose hours proving what someone already knew years earlier.

With good documentation, the response begins further ahead.

The team recognizes the pattern.

They know where to look.

They understand the dependencies.

They follow a tested recovery path.

What once required hours or days can be resolved in minutes.

Documentation turns experience into reusable speed.

The Most Dangerous Dependencies

Every system has dependencies.

Most are obvious.

Some are invisible until everything else has already failed.

One incident I participated in taught this lesson in unforgettable fashion.

A backup generator existed exactly as designed.

Fuel was available.

The contingency plan appeared complete.

But one critical dependency had never been questioned.

The fuel pump that supplied the generator was powered by the generator itself.

When the generator exhausted its immediate fuel supply, it stopped producing electricity.

The moment it stopped, the fuel pump also stopped.

There was fuel available.

There was a generator available.

But there was no way to connect the two because the recovery mechanism depended upon the very system it was attempting to recover.

It was a single design oversight with enormous consequences.

The most dangerous dependencies are often the ones no one realized were dependencies.

That lesson deserved far more than a verbal story.

It deserved documentation.

---

Institutional Memory

Organizations forget.

Not because people are careless.

Because people move.

They retire.

They change teams.

They accept promotions.

Companies merge.

Knowledge leaves every day.

Without documentation, organizations slowly suffer from institutional amnesia.

Every generation of engineers rediscovers problems that another generation already solved.

The same mistakes are repeated.

The same outages occur.

The same lessons are relearned at full price.

Experience compounds only when knowledge survives the people who gained it.

---

Documentation Is Leadership

Documentation is often viewed as an engineering task.

It is actually an act of leadership.

When you document your work, you respect the people who will inherit it.

You reduce onboarding time.

You increase confidence.

You eliminate guesswork.

You empower others to succeed without requiring your presence.

The greatest engineers do not make themselves indispensable.

They make the organization resilient without them.

---

Write for the Person Who Knows Nothing

One of the hardest habits to develop is writing for someone who has no context.

Not because they are unintelligent.

Because they have not lived your experience.

Avoid unexplained acronyms.

Define assumptions.

Record prerequisites.

Explain why decisions were made.

Document failed approaches as well as successful ones.

The goal is not to impress the reader.

The goal is to help them succeed.

Write documentation for the person you once were, not the expert you are today.

---

Good Documentation Answers Questions

The best documentation anticipates the next question before it is asked.

What does this system do?

Why does it exist?

How is it built?

How do I monitor it?

How do I recover it?

What breaks if I change it?

Who depends on it?

When documentation answers these questions, support becomes predictable instead of investigative.

---

Closing Thought

Every solution eventually becomes someone else's inheritance.

Leave them more than functioning systems.

Leave them understanding.

Leave them confidence.

Leave them the knowledge to succeed without having to repeat your mistakes.

Documentation is the only way experience continues working after its author has gone home.

Documentation Builds Trust

Well-documented systems inspire confidence.

Not because they never fail.

Because people know how they work.

They know how to maintain them.

They know how to recover them.

Confidence is not created by perfection.

It is created by understanding.

People trust systems they understand. Documentation creates that understanding.

---

Documentation Is an Investment

Writing documentation feels slower today.

Searching for missing knowledge is far slower tomorrow.

Every hour invested documenting a system is an hour that may save dozens—or hundreds—of hours over its lifetime.

Documentation compounds exactly like experience.

The return is rarely immediate.

It is almost always substantial.

---

The Documentation Test

Before declaring any project complete, ask yourself:

Could a competent engineer who has never seen this system successfully operate it?

Recover it?

Upgrade it?

Troubleshoot it?

Explain why it exists?

If the answer is "no," the project is still incomplete.

---

Failure Modes

Documentation often fails in predictable ways.

It becomes outdated because nobody owns it.

It becomes enormous because nobody curates it.

It becomes so technical that nobody can read it.

Or it never gets written because everyone intends to "come back later."

Later rarely arrives.

Documentation should be living knowledge.

Reviewed.

Improved.

Versioned.

Maintained with the same discipline as the systems it describes.

Outdated documentation is frustrating. Missing documentation is dangerous.

---

In Practice

Before you close a project:

• Explain what was built.
• Explain why it was built.
• Record the assumptions.
• Identify the dependencies.
• Document monitoring.
• Document backups.
• Document recovery.
• Record known limitations.
• Capture lessons learned.
• Write the Cause of Event after every significant incident.

Future engineers should never have to reverse-engineer your thinking.

---

Questions to Ask Yourself

• If I left tomorrow, could someone continue this work?
• Have I documented why, not just how?
• What assumptions exist only in my head?
• Have I captured the recovery process?
• Would my documentation help someone at two in the morning during a major outage?

---

Founder's Commentary

Why This Principle Exists

Technology changes constantly.

Human memory does not improve with complexity.

Every year our systems become larger, more interconnected, and more dependent upon people understanding decisions made years earlier.

Documentation transforms personal knowledge into organizational capability.

It allows experience to survive retirement, promotion, mergers, acquisitions, and the simple passage of time.

That is why I consider documentation a feature—not an afterthought.

Relationship to Other Principles

Documentation supports stewardship.

It leaves systems better than we found them.

It demonstrates that details matter.

It respects the next engineer as much as the current one.

Universality Test

This Principle applies far beyond technology.

Doctors document patient care.

Pilots document incidents.

Scientists document experiments.

Teachers document lesson plans.

Families document history.

Civilizations document knowledge.

Whenever people hope that wisdom survives them, documentation is the mechanism that makes it possible.

---

Closing Thought

One day, someone you will never meet will inherit something you built.

Whether they inherit confusion or clarity depends on the documentation you leave behind.

Your greatest contribution may not be the system you built. It may be the understanding you left behind.

---