Documentation Conventions

Q: Document private items?

pub(crate) docs for complex modules; not required on every fn.

Documentation conventions keep Rust knowledge where engineers work: /// rustdoc for APIs, docs/adr/ for decisions, runbooks for on-call, and README files with ownership - not scattered wikis that drift from main.

Recipe

Quick-reference recipe card - copy-paste ready.

service-repo/
  README.md           # quickstart, owners, links
  docs/
    adr/
    runbooks/
    specs/
  crates/*/src/lib.rs # module-level //! docs

When to reach for this:

New service bootstrap
Audit finds missing runbooks
Open source release prep
Onboarding complaints "can't find how to deploy"

Working Example

//! Orders domain logic - money calculations in integer cents.
//!
//! # Examples
//! ```
//! use orders_domain::total_cents;
//! assert_eq!(total_cents(100, 20).unwrap(), 120);
//! ```
 
pub fn total_cents(subtotal: i64, tax: i64) -> Result<i64, &'static str> {
    if subtotal < 0 || tax < 0 {
        return Err("negative amount");
    }
    Ok(subtotal + tax)
}

# docs/runbooks/pool-exhaustion.md
See lesson LL-0042. Steps: check acquire p95, verify DATABASE_MAX_CONNECTIONS, rollback if deploy correlated.

Deep Dive

Doc Types

Type	Location	Audience
rustdoc	`src/`	Crate consumers
ADR	`docs/adr/`	Future maintainers
Runbook	`docs/runbooks/`	On-call
Tech spec	`docs/specs/`	PM + eng delivery
SME site	`site/rust/`	Fleet learning

Quality Bar

Examples compile (cargo test --doc).
ADR status current (Proposed/Accepted/Superseded).
Runbook last_verified date within 90 days.
README updated on ownership change same PR.

Sync with SME Site

Internal articles summarize patterns; repo docs are source of truth for service-specific commands and SHAs.

Gotchas

Wiki-only runbooks - Stale after refactor. Fix: Runbooks in repo; wiki links only.
Empty //! module docs - Fix: Required for public crates in CI check.
ADR not linked from README - Fix: "Architecture" section with last 5 ADRs.
Copy-paste kubectl from prod - Fix: Parameterize env in runbook templates.

Alternatives

Alternative	Use When	Don't Use When
mdBook for crate book	Large public OSS	Tiny internal lib
Notion for specs	PM collaboration	Sole deploy/runbook store
auto-doc from OpenAPI	HTTP surface	Domain logic teaching

FAQs

Document private items?

pub(crate) docs for complex modules; not required on every fn.

ADR vs RFC archive?

RFC folder holds proposals; accepted become ADR.

Non-English docs?

English default for fleet; product may localize user-facing only.

Generated docs in CI?

Publish rustdoc to internal portal on release tags.

Comment when not when?

Why not what; link ADR for non-obvious trade-offs.

Architecture Decision Records - ADR process
Contribution Guidelines - how to update docs
Coding Standards - doc examples
Incident Response Playbooks - runbook content
Governance Best Practices - summary

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

Recipe

Quick-reference recipe card - copy-paste ready.

service-repo/
  README.md           # quickstart, owners, links
  docs/
    adr/
    runbooks/
    specs/
  crates/*/src/lib.rs # module-level //! docs

When to reach for this:

New service bootstrap
Audit finds missing runbooks
Open source release prep
Onboarding complaints "can't find how to deploy"

Working Example

//! Orders domain logic - money calculations in integer cents.
//!
//! # Examples
//! ```
//! use orders_domain::total_cents;
//! assert_eq!(total_cents(100, 20).unwrap(), 120);
//! ```
 
pub fn total_cents(subtotal: i64, tax: i64) -> Result<i64, &'static str> {
    if subtotal < 0 || tax < 0 {
        return Err("negative amount");
    }
    Ok(subtotal + tax)
}

# docs/runbooks/pool-exhaustion.md
See lesson LL-0042. Steps: check acquire p95, verify DATABASE_MAX_CONNECTIONS, rollback if deploy correlated.

Deep Dive

Doc Types

Type	Location	Audience
rustdoc	`src/`	Crate consumers
ADR	`docs/adr/`	Future maintainers
Runbook	`docs/runbooks/`	On-call
Tech spec	`docs/specs/`	PM + eng delivery
SME site	`site/rust/`	Fleet learning

Quality Bar

Examples compile (cargo test --doc).
ADR status current (Proposed/Accepted/Superseded).
Runbook last_verified date within 90 days.
README updated on ownership change same PR.

Sync with SME Site

Internal articles summarize patterns; repo docs are source of truth for service-specific commands and SHAs.

Gotchas

Wiki-only runbooks - Stale after refactor. Fix: Runbooks in repo; wiki links only.
Empty //! module docs - Fix: Required for public crates in CI check.
ADR not linked from README - Fix: "Architecture" section with last 5 ADRs.
Copy-paste kubectl from prod - Fix: Parameterize env in runbook templates.

Alternatives

Alternative	Use When	Don't Use When
mdBook for crate book	Large public OSS	Tiny internal lib
Notion for specs	PM collaboration	Sole deploy/runbook store
auto-doc from OpenAPI	HTTP surface	Domain logic teaching

FAQs

Document private items?

pub(crate) docs for complex modules; not required on every fn.

ADR vs RFC archive?

RFC folder holds proposals; accepted become ADR.

Non-English docs?

English default for fleet; product may localize user-facing only.

Generated docs in CI?

Publish rustdoc to internal portal on release tags.

Comment when not when?

Why not what; link ADR for non-obvious trade-offs.

Architecture Decision Records - ADR process
Contribution Guidelines - how to update docs
Coding Standards - doc examples
Incident Response Playbooks - runbook content
Governance Best Practices - summary

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

Documentation Conventions

Buscar en la documentación

Documentation Conventions