Status: Accepted

Date: June 2026

Context

As Rundown OS has grown, it has become clear that different documents serve different purposes. Mixing long-term engineering standards with implementation guides and quick-reference material makes the documentation harder to maintain and navigate.

A clear information architecture is required so that documentation remains scalable as Rundown OS evolves.

Decision

Rundown OS documentation is divided into four categories:

• Handbook — Defines engineering standards, principles, and architectural decisions.

• Guides — Explain how to implement or operate systems according to the handbook.

• Reference — Provides concise lookup information such as naming conventions, commands, and checklists.

• ADRs — Record significant engineering decisions and the reasoning behind them.

Each document should belong to exactly one category.

Reasoning

Separating documentation by purpose:

• Improves discoverability.

• Reduces duplication.

• Keeps engineering standards stable.

• Allows implementation guidance to evolve independently.

• Simplifies onboarding for new developers.

This structure mirrors documentation practices used by mature engineering organizations while remaining appropriate for Rundown's scale.

Consequences

Positive

• Stable handbook with infrequent changes.

• Practical guides that can evolve over time.

• Fast access to reference information.

• Clear distinction between standards and implementation.

Negative

• Requires discipline when adding new documents.

• Some topics may require links across multiple categories.

Review Criteria

This decision should be reviewed if the documentation structure becomes difficult to navigate or if new categories emerge that cannot be reasonably represented within the existing information architecture.

Until then, this remains the official documentation structure for Rundown OS.