Software Practices

Examples

Small uses that teach an API or prove an integration path.

16 items in this guidance cluster.

Tagged guidance

Guide item

GuideDocumentationRustdocSource TruthMarkdown And Documentationmarkdown-documentationMarkdown and documentation guidance covers lintable Markdown, reader paths, page modes, Rustdoc, examples, references, and reusable guidance style. It favors current behavior, task-first user docs, durable source links, and prose that preserves local voice.

Documentation rules

RuleDocumentationRustdocVerificationBuild Docs Like Users Read ThemDOCS-BUILD-DOCS-LIKE-USERS-READ-THEMReview rendered Rust documentation, links, cfg behavior, and examples in the modes users see. Match validation depth to the risk of feature, metadata, or public example changes.RuleDocumentationVerificationDistinguish Example RolesDOCS-DISTINGUISH-EXAMPLE-ROLESName whether an example is focused, canonical, survey, integration, or showcase work. That role controls how complete, copyable, and validated the example must be.RuleDocumentationReviewabilityAgent WorkflowExpose Move, Risk, and Example in PatternsDOCS-EXPOSE-MOVE-RISK-AND-EXAMPLE-IN-PATTERNSGive pattern guidance a recognizable trigger, preferred move, risk, example, and agent instruction. The extra structure makes repeatable advice easier to cite and apply.RuleDocumentationVerificationRustdocMark Noncompiling Examples HonestlyDOCS-MARK-NONCOMPILING-EXAMPLES-HONESTLYLabel examples that are sketches, partial snippets, or intentionally not run. Honest labels keep readers from treating illustrative code as a supported copy-paste contract.RuleDocumentationVerificationPublic APIProve Real Use With ExamplesDOCS-PROVE-REAL-USE-WITH-EXAMPLESUse examples that show realistic ownership, errors, lifecycle, configuration, or integration shape. Keep them focused, but make them strong enough to prove the contract.RuleDocumentationSource TruthReader LocalitySeparate Technique From Example PolicyDOCS-SEPARATE-TECHNIQUE-FROM-EXAMPLE-POLICYTraining examples should distinguish the library or framework technique being taught from application-specific policy. Explain the policys rationale, tradeoffs, and meaningful edge cases, then tell readers what to reuse and what to reconsider.RuleDocumentationSide EffectsVerificationShow Side Effects in Live ExamplesDOCS-SHOW-SIDE-EFFECTS-IN-LIVE-EXAMPLESShow setup, visible effects, and cleanup when examples touch live resources or persistent state. Gate costly or externally visible actions so examples stay honest and safe to adapt.RuleDocumentationReader LocalityUse Concrete DetailsDOCS-USE-CONCRETE-DETAILSName real commands, paths, defaults, types, examples, and work areas when they clarify scope. Concrete detail removes guesswork without overloading prose with incidental facts.

Rust rules

RuleRustRustdocDocumentationAvoid Vague Docs and Generic ExamplesRUST-AVOID-VAGUE-DOCS-AND-GENERIC-EXAMPLESWrite Rustdoc and examples around real caller scenarios, not generic claims of usefulness. Concrete examples expose ownership, errors, features, and lifecycle expectations.RuleRustRustdocDocumentationKeep Rustdoc and README Examples AlignedRUST-KEEP-RUSTDOC-AND-README-EXAMPLES-ALIGNEDKeep README, Rustdoc, generated docs, and example directories teaching the same current usage contract. Aligned examples prevent users from guessing which import path or lifecycle is correct.

Testing rules

RuleTestingRustdocVerificationCover Public Examples with DoctestsTEST-COVER-PUBLIC-EXAMPLES-WITH-DOCTESTSCompile public documentation examples as doctests when they do not need fragile state. Executable examples catch stale guidance, reserving no-run or ignored examples for real limits.RuleTestingDocumentationAutomationRun Docs as a First-Class GateTEST-RUN-DOCS-AS-FIRST-CLASS-GATETreat documentation checks as real validation for examples, links, commands, and claims. Prose-only edits may need less proof, but API-facing docs should fail before stale guidance ships.RuleTestingBoundary CorrectnessValidation PolicyUse Realistic Parser SamplesTEST-USE-REALISTIC-PARSER-SAMPLESTest parsers with representative input, malformed cases, and safe degradation examples. Real samples catch compatibility failures, but fixtures should be minimized and scrubbed.

Pattern item

PatternRustRustdocDocumentationRun Rustdoc Quality Passrun-rustdoc-quality-passUse a bounded checklist when raising a Rust crates public documentation. The pass should teach the crate model, document public contracts, place examples where they prove real use, keep documentation layers aligned, and validate Rustdoc as code.

Mechanism item

MechanismRustRustdocDocumentationRust Docs Validationrust-docs-validationDoctests, Rustdoc warnings, rendered docs, and docs.rs-style builds prove documentation surfaces the way users will see them. Use this mechanism when examples, public API docs, feature docs, or release-facing documentation changes.