Skip to content
rust-template

ADR-0002: Documentation Directory Structure

Status

Section titled “Status”

Accepted

Context

Section titled “Context”

As the rust_template project grew to include 30+ CI/CD workflows, security tooling, release automation, and AI coding agent support, the documentation expanded organically. Files were spread across multiple subdirectories (docs/workflows/, docs/security/, docs/distribution/, docs/testing/, docs/ux/, docs/observability/) without a clear organizing principle.

This created two problems:

  1. New users who clicked “Use this template” had no guided path from repository creation to first CI pass. They had to discover relevant documentation by browsing directories.
  2. Maintainers performing routine operations (releases, dependency updates, security responses) had no centralized runbooks. Operational knowledge was scattered across deployment guides and workflow-specific docs.

The existing documentation was accurate but lacked audience-aware organization.

Decision

Section titled “Decision”

We will organize documentation into two audience-targeted directories:

docs/template/ — Template adoption guides (for new users)

Section titled “docs/template/ — Template adoption guides (for new users)”

Files that help developers who just created a repository from this template get productive quickly:

  • GETTING-STARTED.md — End-to-end guide from “Use this template” to first CI pass
  • CONFIGURATION.md — Cargo.toml fields, placeholder replacement, feature flags, editor setup
  • CI-WORKFLOWS.md — Comprehensive guide to every included workflow
  • CUSTOMIZATION.md — Adding modules, removing examples, adjusting lints, modifying targets
  • GITHUB-TEMPLATE-FEATURES.md — What copies from templates and what doesn’t (relocated)
  • COPILOT-JUMPSTART.md — Copilot scaffolding prompts (relocated)

docs/runbooks/ — Operational runbooks (for maintainers)

Section titled “docs/runbooks/ — Operational runbooks (for maintainers)”

Step-by-step procedures for ongoing project operations:

  • RELEASING.md — End-to-end release process
  • DEPENDENCY-UPDATES.md — Dependabot policy, manual auditing, adding/removing dependencies
  • SECURITY-RESPONSE.md — Vulnerability triage, fix, and disclosure
  • CI-TROUBLESHOOTING.md — Common CI failure patterns and fixes

Retained directories

Section titled “Retained directories”

Existing deep-dive documentation (docs/workflows/, docs/security/, docs/distribution/, docs/testing/, docs/ux/, docs/observability/) is retained as detailed reference material. The new template and runbook guides link to these files where appropriate.

A docs/README.md serves as a documentation index linking all guides and references.

Consequences

Section titled “Consequences”

Positive

Section titled “Positive”
  • Reduced adoption toil: New users have a clear guided path from template to working project
  • Faster operations: Maintainers have centralized runbooks for routine tasks
  • Audience clarity: Documentation is organized by who reads it and when
  • Discoverability: docs/README.md index makes all documentation findable

Negative

Section titled “Negative”
  • Two levels of documentation: Some topics are covered at both the guide level (template/runbooks) and reference level (existing subdirectories), requiring cross-linking
  • Maintenance burden: Changes to workflows may need updates in both CI-WORKFLOWS.md and the corresponding workflow-specific doc

Neutral

Section titled “Neutral”
  • Existing workflow and reference documentation is preserved unchanged
  • The docs/adr/ directory remains at its current location