Documentation Conventions
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 //! docsWhen 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_verifieddate 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.
Related
- 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+.