Select a result to preview

Documentation Standards

Document: 10-documentation-standards.md
Version: 1.0.0

Purpose

This document defines the documentation standards followed across all Rundown projects.

Documentation ensures that projects remain understandable, maintainable, and transferable throughout their lifecycle. Every project should include sufficient documentation to allow another developer to understand the project, deploy it, and maintain it without requiring additional explanation.

Documentation is considered part of the deliverable and should be maintained alongside the codebase.

Documentation Principles

Documentation should be:

If documentation becomes outdated, it should be updated as part of the same change that introduced the code.

Required Project Documentation

Every Rundown project must include the following documentation.

project/

README.md

CHANGELOG.md

.env.example

docs/

The docs directory contains all project-specific documentation.

README.md

Every repository must include a README.

The README should answer the following questions:

The README should remain concise and serve as the entry point into the project documentation.

CHANGELOG.md

Every project should maintain a changelog.

The changelog records significant updates made throughout the project's lifetime.

Examples include:

The changelog should follow Semantic Versioning where applicable.

Environment Documentation

Every repository must include:

.env.example

This file should contain:

Sensitive information must never be committed to version control.

Project Documentation

The docs directory should follow the standard structure below.

docs/

architecture.md

deployment.md

integrations.md

handover.md

troubleshooting.md

Projects may add additional documentation when required, but the standard files should remain consistent across all Rundown projects.

architecture.md

Purpose:

Provide a high-level overview of the application architecture.

Typical contents include:

deployment.md

Purpose:

Document the deployment process.

Typical contents include:

Deployment documentation should allow another developer to successfully deploy the application.

integrations.md

Purpose:

Document all third-party integrations.

Examples:

Each integration should include:

handover.md

Purpose:

Provide information required when transferring the project to another developer or the client.

Typical contents include:

troubleshooting.md

Purpose:

Document common issues and their resolutions.

Examples include:

Whenever a recurring issue is resolved, it should be documented here.

Inline Code Documentation

Code comments should explain:

Avoid comments that merely describe what the code is doing.

Self-explanatory code should not require comments.

API Documentation

Projects exposing APIs should document:

API documentation should remain synchronized with implementation changes.

Architecture Decisions

Significant architectural decisions should be recorded as Architecture Decision Records (ADRs).

Examples include:

Project-specific ADRs should remain separate from Rundown OS ADRs.

Client Documentation

Client-facing documentation should be written separately from internal engineering documentation.

Examples include:

Technical implementation details intended for developers should not be included in client documentation.

Documentation Maintenance

Documentation should be reviewed whenever:

Updating documentation should be considered part of completing the associated development work.

Engineering Decision

Documentation Philosophy

Status: Accepted

Decision

Documentation is maintained alongside the codebase and treated as a required deliverable.

Reasoning

Well-maintained documentation:

Documentation Checklist

Before completing a feature or release, verify:

Summary

Documentation preserves knowledge and ensures that Rundown projects remain understandable long after initial development.

Maintaining accurate documentation reduces operational risk, simplifies collaboration, and enables projects to evolve without relying on tribal knowledge.