Documentation and Test Standards

These standards are meant to keep the project useful for contributors without turning it into process theater.

Documentation Standard

Document actual behavior first.

Good documentation should answer one of these questions:

• What can a user or contributor do today?
• What behavior does the code currently provide?
• What decision has been made, and why?
• What is planned, and how clearly is it marked as planned?
• What is intentionally out of scope?

Avoid docs that read like completed product copy when the behavior does not exist.

Mark Planned Work

Use a short callout when documenting plans, design intent, or reserved sections:

> Planned: This describes intended behavior. It is not implemented yet.

Use a different callout for unsettled design:

> Open question: This design has not been decided yet.

If a page mixes current and planned behavior, put the current behavior first and label planned sections directly.

Keep Docs Structured By Audience

User-facing docs should explain workflows, current capabilities, limitations, and what the project is trying to become.

Contributor-facing docs should explain setup, architecture, crate boundaries, roadmap context, standards, and open design questions.

Architecture docs should describe current boundaries and decisions. If they describe a target shape, mark it as planned or recommended.

Design notes should explain why a choice was made, what alternatives were considered, and what would cause the project to revisit the choice.

Documentation Locations

• README.md: project identity, current status, quick start, contribution entry points
• CONTRIBUTING.md: contributor workflow and expectations
• doc/src/users/: user-facing product and workflow docs
• doc/src/contributors/: contribution standards and maintainer expectations
• doc/src/concepts/: product concepts and vocabulary
• doc/src/architecture/: current architecture and technical design
• doc/src/roadmap/: roadmap horizons and status
• doc/src/api/: API design and query behavior
• doc/src/operations/: local operations and development notes

Test Standard

Tests should focus on behavior that matters.

Prefer tests for:

• domain invariants and validation
• application service behavior
• storage contract behavior
• HTTP status codes, request/response shape, routing, and error cases
• query parsing and filtering behavior
• regressions that affected real behavior

Avoid tests that only assert implementation details, duplicate the code line-by-line, or make refactoring harder without protecting behavior.

Test Names

Use test names that describe the behavior:

#![allow(unused)]
fn main() {
#[test]
fn creating_project_requires_non_empty_name() {
    // ...
}
}

Prefer externally visible language over internal mechanics when possible.

When Behavior Is Ambiguous

Do not invent behavior in tests or docs just to make a gap look complete.

Instead:

• add a small test for the behavior that is already clear
• mark the uncertainty as an open question in docs
• propose the decision separately when it affects product direction

Review Checklist

Before merging docs or tests, ask:

• Is this describing implemented behavior, a decision, or a clearly marked plan?
• Would a new contributor know what to do next?
• Does the test protect meaningful behavior?
• Does the test make future refactoring harder for no product benefit?
• Is the documentation likely to become stale because it overpromises?