Documentation

README, guide, reference, and contract prose used to understand current behavior.

111 items in this guidance cluster.

Tagged guidance

Documentation workflowDocumentation-workflow guidance covers deciding what documentation work belongs in a change, how deep the edit should go, and how review-facing prose should carry evidence. It keeps documentation scope explicit so local fixes, page rewrites, repo maps, and review narratives do not collapse into one unreviewable pass.Markdown and 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.

Define good before judgment-heavy workState the quality bar before work where taste, naming, API shape, or review expectations matter. Clear criteria give the agent goalposts before it creates a large speculative diff.Distill from blessed artifactsStudy accepted code, docs, tests, and reviews first. Adapt local convention to this task.Keep durable context on diskStore project facts, accepted decisions, and long-lived operating notes in files instead of relying on chat context. Durable context makes future sessions and reviews resumable.Prefer tools over promptsMove repeated instructions into tools, checks, templates, or durable guides. Tooling catches failures even when prompts are short, compacted, or interpreted differently.Produce review packetsHand off agent work with purpose, changed files, evidence, skipped checks, risks, and follow-ups. A review packet lets maintainers inspect the output without replaying the session.Turn feedback into guidanceConvert repeated review corrections into rules, templates, snippets, or checks. Durable guidance fixes the workflow problem instead of requiring the same steering again.Use AGENTS.md as mapKeep AGENTS.md compact by using it to route agents to deeper guides and mechanisms. Treating it as a map preserves startup context without losing durable project guidance.

Prefer small follow-upsMove adjacent cleanup or broader improvements into focused follow-up changes when the current diff can stand alone. This preserves review focus while still capturing useful work.

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.Avoid generated prose tellsReplace templated, UI-centered, or polished-but-vague phrasing with concrete behavior. Keep the local voice trustworthy without cutting useful explanation.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.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.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.Compare libraries accuratelyCheck current upstream behavior before comparing nearby libraries or crates. Charitable, source-backed comparisons preserve trust while still helping users choose.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.Document lifecycle and side effectsDocument caller-visible lifecycle, ownership, platform, feature, and side-effect obligations. Skip internal narration, but make operational responsibilities clear.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.

Explain PR problem model and proofUse PR descriptions to explain the problem, mental model, tradeoffs, validation, and documentation impact. Reviewers can then evaluate the diff against stated intent instead of reverse-engineering it.Label speculation as inferred or unknownMark review claims as observed, inferred, assumed, or unknown when the evidence level matters. Clear labels keep guesses from hardening into false project knowledge.Make review artifacts standalonePut the needed problem, decision, context, validation, and risk in the issue, PR, commit, or handoff itself. Standalone artifacts make review and future debugging possible without private session context.Update source of truthPut durable status changes in the owning issue, PR description, checklist, plan, or handoff instead of posting low-signal comments. Updating the source of truth reduces notification churn and makes the current state discoverable.Use ADRs for boundaries and ownershipRecord durable ownership, API, storage, topology, runtime, or service-boundary decisions in ADRs. A decision record gives later contributors a stable tradeoff to affirm, revise, or replace.

Align release support claimsKeep crate metadata, docs, changelogs, and support statements saying the same thing. The alignment helps downstream users know which compatibility contract to trust.Avoid giant crate rootsUse the crate root to teach the public shape and route readers to focused modules. This keeps lib.rs or main.rs from becoming the whole implementation surface.Avoid overcommenting trivial codeComment Rust code for invariants, contracts, and surprising tradeoffs rather than restating obvious operations. This keeps comments useful and less prone to drift.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.Compare crates by fit and tradeoffCompare adjacent crates by intended fit, scope, and constraints instead of broad superiority claims. This helps users choose without turning docs into brittle marketing.Configure docs.rsConfigure docs.rs metadata when features, cfgs, or rustdoc flags affect rendered API docs. Users should see the documentation surface the crate expects to support.Document current implemented behaviorDocument what the crate does today instead of presenting future plans as available contract. Clear tense and labels prevent callers from relying on unimplemented behavior.Document feature contractsExplain what each feature flag enables, requires, and promises. Feature contracts help users choose combinations without guessing from dependency names.Document lifecycle side effectsDocument construction, start, stop, drop, and cleanup behavior when side effects matter. Callers need to know when resources are acquired, released, spawned, or blocked.Document performance contractsState meaningful performance expectations when callers may design around them. Clear limits keep complexity and optimization claims tied to supported behavior.Document public panic contractsDocument when public APIs can panic and what callers can do to avoid it. Panic contracts keep recoverable errors, invariants, and misuse boundaries explicit.Document scheduling for long async workExplain executor, cancellation, blocking, and fairness expectations for async work that can run long. Callers need those constraints to avoid starvation and runtime surprises.Document visibility ownershipPair widened visibility with names and docs that identify the owning concept. This prevents shared internals from looking like accidental stable API.Format docs and comments consistentlyApply stable formatting to Rustdoc, examples, attributes, and prose comments. Consistent source formatting keeps docs readable and prevents noisy future diffs.Keep Markdown outside rustdoc purposefulUse standalone Markdown for architecture, workflow, release, or operational guidance that would make API docs noisy. Choosing the right surface keeps contracts and long-form context current.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.Teach crate from crate rootUse crate-root docs and exports to teach the crates main concepts, entry points, and common paths. Keep the root focused enough to orient readers without duplicating every item-level contract.Tie optional dependencies to named featuresConnect optional dependencies to clear feature names that explain the capability callers enable. Avoid leaking dependency names as the public feature design when the capability needs a more stable contract.Use directory modules as tables of contentsLet directory module files introduce, organize, and re-export the concepts owned by that directory. Keep substantial implementation in named child files so the module remains a readable table of contents.Write public docs for caller tasksWrite public Rustdoc around what callers are trying to decide, do, and rely on. Start with concise behavior and add arguments, failures, lifecycle, features, links, or examples only when they help the task.Write rustdoc as API contractUse Rustdoc to state caller-facing behavior, invariants, failures, side effects, and compatibility promises. Leave private implementation detail in comments unless it helps maintain the public contract.

Generalize project-specific rulesExtract the portable failure mode before promoting local lessons into shared guidance. Provider, repo, or tool details should stay local unless they clarify the durable rule.Make shared artifacts standaloneRestate the problem, rationale, evidence, and tradeoffs in shared docs, templates, generated packs, or reusable guidance. Future readers should not need private notes or transcripts to trust the artifact.Prefer primary stable sourcesAnchor durable guidance in sources readers can inspect, compare, and challenge. Use links to clarify judgment, not to decorate rules or depend on private memory.

Keep drift claims alignedTie support claims, fixtures, examples, docs, and API paths to executable drift checks. Stable claims need evidence, but wording-only changes should not break broad tests.Run docs as a 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.

Ask what were you trying to achieveRecover the original intent before judging a surprising design. Separating purpose from mechanism makes it easier to preserve useful constraints while replacing stale structure.Bootstrap repo docsRepositories without a documentation map make newcomers infer structure from scattered files and conventions. Add the smallest durable entry points that explain purpose, layout, commands, and where deeper guidance belongs.Choose doc pass depthDocumentation work ranges from quick polish to structural repair, and using the wrong pass depth wastes attention. Match the edit depth to the evidence, risk, and review need before changing the document.Choose doc typeA documentation need can call for a guide, reference, tutorial, decision record, or checklist, and mixing those jobs makes docs harder to use. Pick the type that fits the readers task before deciding structure or tone.Delete redundant commentsComments that repeat obvious code add reading burden and become stale faster than the behavior they describe. Remove them or replace them with context that explains intent, invariant, risk, or non-obvious tradeoff.Deliver context just in timeToo much context up front overloads the reader, while too little context forces rediscovery. Provide the next useful fact at the point of decision, linking outward when deeper background is optional.Distill from blessed artifactsDurable guidance should come from accepted examples, reviewed decisions, and working artifacts rather than transient preferences. Distill stable lessons from blessed sources and keep uncertain ideas marked as draft.Document errors panics safetyCallers need to know which failures are recoverable, which conditions panic, and what safety obligations an API imposes. Document those contracts at the public boundary so users can compose the API deliberately.Document intentional non goalsReaders may treat missing behavior as oversight when the absence was a deliberate scope choice. Record important non-goals where they prevent repeated debate or misuse without turning the document into a defensive catalog.Document system mental modelsSystems with implicit concepts force readers to reconstruct how parts fit together from scattered implementation details. Document the mental model that explains ownership, flow, boundaries, and vocabulary before listing procedures.Keep docs near their subjectDocumentation drifts when it is far from the code, policy, or workflow it explains. Let shared rationale rise to the nearest stable owner while item docs retain their local contracts, differences, edge cases, and side effects.Keep name currentNames that preserve old intent make readers distrust the code or documentation around them. Rename when the concept changes enough that the old name now teaches the wrong model.Label doc claims by evidenceDocumentation loses trust when speculation, observed behavior, policy, and verified facts look the same. Label claims by their evidence level so readers know what can be relied on and what still needs confirmation.Make side effects visibleCallers need to know when an operation touches persistence, networks, time, global state, caches, metrics, processes, or other external systems. Make caller-relevant effects visible in names, docs, or examples without documenting implementation noise.Prefer 100-column prose wrapWrap Markdown prose and Markdown-bearing doc comments around 100 columns as a maintainer readability preference. The exact number is subjective, but it balances source reading, monospace density, review diffs, and common screen sizes better than 80 or 120 columns.Prefer durable summariesImportant context is costly when every reader must rediscover it from implementation details, but exhaustive narration becomes stale. Capture stable invariants, rationale, boundaries, or side effects in short summaries that survive nearby changes.Preserve local doc voiceDocumentation edits can become bland or mismatched even when they are grammatically correct. Patch only what needs changing while keeping local terms, structure, density, and tone unless the existing voice blocks clarity or accessibility.Reconstruct rationale before writingExplanations become plausible stories when writers infer intent from current code and consult history only to fill gaps. Reconstruct the decision from present behavior, introducing and corrective changes, tests, measurements, and discussion before drafting the durable account.Record agent operating lessonsAgent work produces useful operational knowledge that is easy to lose after the task succeeds or fails. Record reusable lessons in the right durable place so future runs inherit the improved workflow instead of rediscovering it.Remediate doc driftDocumentation drift misleads readers when behavior, workflow, or project shape has moved on. Fix the source of truth and nearby references together, choosing whether the code or the doc represents the intended contract.Run 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.Run source explanation passTurn a source tree into a self-contained reading environment by recovering its mental models, fundamentals, decisions, constraints, and edge cases. Establish the system map before item detail, audit every relevant helper and path, and measure success through reader comprehension rather than comment count.Use AGENTS.md as mapA giant AGENTS.md grows stale and crowds out the context the agent actually needs. Keep it as a compact map to canonical guides, patterns, commands, and safety rules, with details living in owned files.Use disk as context sinkLarge pasted context is difficult to search, diff, summarize, and revisit. Put bulky or reusable context on disk so agents can pull the relevant slice while the thread stays focused on decisions and handoff.Write docs as contractsBehavior and obligations become surprising when they are only discoverable by reading implementation details. Treat docs as part of the change surface, updating contracts and rationale alongside the code they describe.

Docs are contractsDocumentation near code is part of the supported behavior surface. Keep prose, examples, and implementation aligned so humans and agents can rely on the same contract.Private context is not shared contextShared artifacts must carry the reasoning that downstream readers did not see in the private session. Issues, PRs, commits, guides, and review packets should restate the decision context that matters.

Guidance content model stewardshipContent-model stewardship keeps guides, rules, patterns, principles, mechanisms, references, snippets, and downstream templates in distinct roles. The mechanism combines mechanical inventory checks with maintainer review queues for overlap, thin guidance, noisy tags, and subjective content-quality decisions.Guidance generation and auditGenerators and audits keep rule indexes, compressed agent snippets, downstream templates, and Markdown synchronized. The checks catch recurring drift so review attention stays on judgment instead of mechanical bookkeeping.Project operating manualA project operating manual is a repo-owned document that applies broad software guidance to one live codebase. It turns a large catalog of durable rules into an opinionated project-specific doctrine, decision surface, and review contract so maintainers and agents do not have to reconstruct the totality of what matters here from AGENTS.md plus many scattered guides.Rust 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.Rust lints and formattingRust and Markdown formatting plus targeted project lints encode stable mechanical preferences. The mechanism removes repeat style debate from review while leaving design judgment to humans and higher-level guidance.

Full documentation doctrine prompt packLarge single-file prompt pack for long-term documentation maintenance. It combines the repos docs rules with writing, review, anti-drift, and anti-AI-slop lessons drawn from this repo, TidySrc, jk, and Komodo-style documentation cleanup work.Full software doctrine prompt packLarge single-file prompt pack that combines the repos software rules and the reasons behind them into one coherent artifact. This version is tuned for Rust-heavy maintenance and refactoring work, especially when existing code needs to be reshaped toward better locality, coherence, ownership, and documentation.Markdown and docs agent instructionsCompact documentation instructions for agents editing Markdown, Rustdoc, READMEs, review notes, or adjacent narrative. The snippet focuses on current behavior, local voice, page purpose, drift repair, and markdownlint-compatible formatting.