Docs Are Contracts

Documentation rules cover docs-as-contracts, rendered docs, examples, reviewability, source links, concrete prose, and drift checks.

Behavior contracts, examples, rendered docs, and review-facing evidence.

35 rules

RustdocSource TruthPublic APIAlign README and Crate RustdocDOCS-ALIGN-README-AND-CRATE-RUSTDOCKeep README and crate-level Rustdoc consistent where users learn setup and supported behavior. Let the pages serve different tasks, but prevent conflicting contracts.AIReader LocalityAvoid Generated Prose TellsDOCS-AVOID-GENERATED-PROSE-TELLSReplace templated, UI-centered, or polished-but-vague phrasing with concrete behavior. Keep the local voice trustworthy without cutting useful explanation.VerificationReviewabilityAvoid Unearned PraiseDOCS-AVOID-UNEARNED-PRAISEReplace vague ranking words with observable behavior, evidence, or tradeoffs. Use evaluative claims only when the basis is explicit enough for readers to verify.RustdocVerificationExamplesBuild 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.Reader LocalitySource TruthChoose Document TypeDOCS-CHOOSE-DOCUMENT-TYPEPick the dominant document mode before editing so the page serves one reader task well. Link out to secondary modes instead of blending tutorial, reference, decisions, and changelog.VerificationDependenciesSource TruthCompare Libraries AccuratelyDOCS-COMPARE-LIBRARIES-ACCURATELYCheck current upstream behavior before comparing nearby libraries or crates. Charitable, source-backed comparisons preserve trust while still helping users choose.ExamplesVerificationDistinguish 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.Side EffectsOwnershipPublic APIDocument Lifecycle and Side EffectsDOCS-DOCUMENT-LIFECYCLE-AND-SIDE-EFFECTSDocument caller-visible lifecycle, ownership, platform, feature, and side-effect obligations. Skip internal narration, but make operational responsibilities clear.ReviewabilityAgent WorkflowExamplesExpose 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.Reader LocalityAgent ContextFront-Load Useful PointDOCS-FRONT-LOAD-USEFUL-POINTPut the decision, command, invariant, or warning before broad setup. Readers and agents can then use the page without hunting through introductory prose.Reader LocalityReviewabilityGroup Related List ItemsDOCS-GROUP-RELATED-LIST-ITEMSCluster long lists under useful names when the relationships matter. Keep short or causal material flat or in prose so structure does not add noise.Reader LocalityHide Catalog MechanicsDOCS-HIDE-CATALOG-MECHANICSLead user-facing copy with work areas, artifacts, and destinations instead of IDs or generated structure. Mention catalog mechanics only when citation or contribution work needs them.ToolingLocal ConventionsReviewabilityKeep Markdown LintableDOCS-KEEP-MARKDOWN-LINTABLEUse project Markdown style so formatting stays enforceable and review noise stays low. Treat lint exceptions as intentional local choices, not accumulated drift.ReviewabilitySource TruthMake Guidance Review State VisibleDOCS-MAKE-GUIDANCE-REVIEW-STATE-VISIBLEMark guidance maturity so readers know whether a rule is draft, reviewed, or ready for reuse. Visible state prevents tentative advice from becoming an accidental standard.ReviewabilityReview HandoffMake Review Easy to InspectDOCS-MAKE-REVIEW-EASY-TO-INSPECTPackage documentation changes so reviewers can see scope, evidence, and rendered impact quickly. Small inspectable changes reduce hidden drift and style-only review loops.ExamplesVerificationRustdocMark 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.Reader LocalityReviewabilityMatch Page Shape to Reader TaskDOCS-MATCH-PAGE-SHAPE-TO-READER-TASKShape pages around the readers task, such as learning, choosing, reference, or review. The right structure lowers scan cost without forcing one page to do every job.Reader LocalityLocal ConventionsName Destination, Not DirectionDOCS-NAME-DESTINATION-NOT-DIRECTIONUse labels that name the section, object, or decision the reader will reach. Directional labels make readers follow the page order before knowing whether it is relevant.Reader LocalitySource TruthOne Dominant Mode per PageDOCS-ONE-DOMINANT-MODE-PER-PAGELet each page have one primary mode and move competing material behind links. This keeps readers from paying for tutorial, reference, explanation, and policy at once.AIReviewabilityReader LocalityOwn AI-Assisted ProseDOCS-OWN-AI-ASSISTED-PROSEAI-generated or AI-assisted docs are reasonable to share when human curation makes them author-owned. The published artifact should carry checked claims, reader-sized scope, relevant evidence, real tradeoffs, and local voice.Reader LocalityReviewabilityProse for Relationships, Lists for EnumerationDOCS-PROSE-FOR-RELATIONSHIPS-LISTS-FOR-ENUMERATIONUse prose when causality, contrast, or priority matters, and lists when enumerating parallel items. The shape should reveal the relationship instead of hiding it in bullets.ExamplesVerificationPublic 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.Source TruthReviewabilityPut Uncertainty in Tracked PlacesDOCS-PUT-UNCERTAINTY-IN-TRACKED-PLACESKeep user docs focused on current truth and move unresolved direction to issues, ADRs, or roadmaps. Track speculation where it can be decided instead of implying a promise.Reader LocalitySource TruthREADME as Entry PointDOCS-README-AS-ENTRY-POINTUse README files to orient readers to purpose, setup, first useful use, and deeper docs. Split out manual-level detail when it hides the starting path.ReviewabilityVerificationReview HandoffReview Correctness and Risk FirstDOCS-REVIEW-CORRECTNESS-AND-RISK-FIRSTLead documentation review with false contracts, drift, operability, and unsupported claims before style polish. This separates blocking risk from wording cleanup.ExamplesSource 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.ExamplesSide 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.Source TruthVerificationState Current Behavior, Not AspirationDOCS-STATE-CURRENT-BEHAVIOR-NOT-ASPIRATIONDescribe what the system does now and label limitations or future plans separately. Otherwise roadmap language becomes a false contract for readers and agents.Source TruthPublic APIVerificationTreat Docs as ContractsDOCS-TREAT-DOCS-AS-CONTRACTSTreat supported behavior, commands, errors, and examples in docs as promises readers may rely on. Separate normative claims from background, examples, and future plans.Reader LocalityExamplesUse 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.Reader LocalityLocal ConventionsUse Descriptive HeadingsDOCS-USE-DESCRIPTIVE-HEADINGSWrite headings that name the section content, destination, or decision area. Reserve imperative headings for procedures where the section is truly a step.Source TruthVerificationUse Source Links as SupportDOCS-USE-SOURCE-LINKS-AS-SUPPORTUse references to verify, frame, or contrast local guidance instead of supplying the wording. This keeps the repo voice original while still making claims checkable.VerificationToolingVerify Commands, Paths, and LinksDOCS-VERIFY-COMMANDS-PATHS-AND-LINKSCheck commands, file paths, and linked references because readers treat them as executable instructions. Note assumptions when credentials, services, or platforms prevent a full run.Reader LocalityAgent ContextWrite for Non-Linear ReadersDOCS-WRITE-FOR-NON-LINEAR-READERSGive sections enough local context to work when reached from search, links, review, or retrieval. Avoid repeating the whole introduction; add only the subject and prerequisite needed.Reader LocalityPublic APIWrite Technical ProseDOCS-WRITE-TECHNICAL-PROSEUse direct technical language that carries contracts, commands, evidence, and tradeoffs. Cut marketing, coaching, chat, and page narration when they do not explain the system.