Markdown And Documentation

Use grouped, named lists when a checklist or rule cluster grows past easy scanning. A long flat list can hide whether the page is about document mode, scan path, sentence shape, claim quality, style limits, or evidence. Use Group Related List Items when a list needs internal structure, and use Prose For Relationships, Lists For Enumeration when bullets are carrying explanation that belongs in paragraphs.

Document Mode

• Write technical docs, not marketing, coaching, or chat.
• Pick the document mode before editing.
• Keep one dominant mode per page.
• Explain in explanation pages.
• Guide in setup and how-to pages.
• Describe in reference pages.
• Do not mix documentation modes without a reason.

Scan Path

• Front-load the point in sentences and paragraphs.
• Use fewer, denser sections.
• Use headings for real topic clusters, not micro-points.
• Use descriptive headings on reference pages, indexes, and landing pages.
• Reserve imperative headings for procedures, checklists, and tutorials where the heading names a real step.
• Name destinations, decisions, artifacts, and work areas instead of directing the reader with phrases like start here or use this when.
• Hide catalog mechanics such as rule prefixes, generated indexes, card behavior, and source layout unless citation, automation, or contribution workflow depends on them.

Use Front Load Useful Point, Use Descriptive Headings, Name Destination Not Direction, and Hide Catalog Mechanics when the reader's scan path depends on headings, first sentences, labels, or generated structure.

Prose And Lists

• Use prose for relationships, causality, and tradeoffs.
• Use lists for steps, fields, options, and enumerations.
• Do not use lists as the default explanation format.
• Let a paragraph develop one idea.
• Do not atomize explanation into one-sentence fragments by default.
• Give each sentence one main burden.
• Do not combine explanation, qualification, anticipated confusion, and navigation in one sentence unless the page needs it.
• In comments and Rustdoc, use a blank comment line when the subject, explanatory level, evidence type, or maintainer warning changes. Do not hide a move from mechanism to history or contract to uncertainty inside one continuous block.

Use Write Technical Prose and Prose For Relationships, Lists For Enumeration when prose shape is hiding relationships, tradeoffs, or the main point.

Concrete Claims

• Prefer concrete nouns.
• Prefer real paths.
• Prefer real defaults.
• Prefer real examples.
• Prefer explicit tradeoffs.

Use Use Concrete Details when a doc could name real paths, defaults, commands, types, examples, or tradeoffs instead of generic wording.

Voice And Style

Sentence Voice

• Name the actor.
• Prefer active voice.
• Prefer present tense unless accuracy requires another tense.
• Avoid vague praise words.
• Avoid invented abstractions.
• Avoid idioms when plain language is available.
• Cut filler and signposting.

Replace inflated word choice with the concrete actor, action, contract, evidence, or tradeoff. When verbs such as ensure, handle, support, or manage hide the real behavior, name the command, validation, ownership boundary, or visible outcome instead.

Page Narration

• Do not narrate the page.
• Do not narrate the interface.
• Explain the system instead of explaining what the page will do.
• Avoid unearned ranking words.
• Use words like simplest, easiest, best, fastest, safest, and usually only when the page states the property that earns the claim.
• In explanation and reference pages, do not stage the reader through time.
• Use temporal staging only in actual procedures.
• Avoid contrast templates such as not X, but Y.
• Avoid punctuation as style signaling.
• Do not lean on repeated dashes or colon scaffolding.
• Avoid self-answered rhetorical questions, false suspense transitions, forced analogies, vague attribution, inflated stakes, and invented concept labels unless the page proves why that shape is useful.
• Avoid hedged neutrality, apology phrasing, and permission phrasing when the page needs a concrete position, instruction, or constraint.

Use Avoid Unearned Praise and Avoid Generated Prose Tells when voice, ranking words, page narration, or interface narration weakens technical clarity.

Revision And Evidence

Local Revision

• Do not restate the same point in adjacent paragraphs at different intensity.
• Do not over-introduce sections.
• Do not over-summarize sections.
• Avoid mini-intros before every list.
• Avoid mini-summaries after every section unless they add meaning.
• Watch for disguised listicles, repeated sentence openings, duplicated sections, and one argument restated through multiple framings.
• Cut "comprehensive" padding and unsupported precision that make a draft look more complete than its evidence supports.

Evidence Links

• Link cleanly to deeper pages.
• Do not add bridge prose that explains the link more than the concept.
• Verify claims, defaults, recommendations, and examples against source and behavior.
• State the exact configuration, path, or comparison that evidence covers. A combined test does not explain every term independently, and a historical intent does not override current behavior.
• Lead historical explanations with the present mechanism or tradeoff. Keep chronology only when it supports that model, explains a rejected alternative, or warns about a regression.
• If a draft is smooth but low-signal, merge sections, cut repetition, restore prose continuity, and add specifics.

Use Use Source Links As Support and Verify Commands Paths And Links when a documentation change depends on source claims, commands, paths, defaults, or examples.