STYLE.md

User-facing writing style

This guide covers public editorial, product copy, documentation, and other prose for readers outside the repository. Apply the voice rules in WRITING.md first.

Public prose must be precise, useful, and free of hype. Use a direct, natural voice that reads well aloud.

Leave the reader with a clearer model

• Write for a reader who knows the general subject but has not read the sources, related articles, or internal project material.
• State the page's central claim and why it matters in plain language before adding detail.
• Introduce each person, organization, source, and necessary technical term at first use. Do not make a link carry context the prose has not supplied.
• Make every page understandable on its own. Related links may deepen the explanation but must not be prerequisites.
• Organize explanatory prose around the reader's questions rather than citation handling, repository structures, data schemas, search strategy, or the sequence in which the analysis was produced. A technical reference may mirror a public interface or schema when that structure is the reader's subject.
• Cite the primary source for a reported claim. Use a secondary digest only when it contributes distinct evidence or analysis, and state that contribution without explaining internal citation mechanics.
• Label personal observations, controlled benchmarks, official specifications, and forecasts accurately. Do not turn an anecdote into a general finding or a possible cause into the only cause.
• Do not invent an opposing claim, conflict, or consequence to manufacture an argument. If a source does not connect two topics, connect them only with independent evidence that helps answer the reader's question.
• Do not expose private implementation details, internal reasoning, or editorial process. A technical reference may document only the public interface, schema, and behavior readers need to use or evaluate the product. In explanatory prose, state the supported conclusion, the evidence a reader can inspect, and the limitations that affect it.
• Connect an external source to the product only when the connection helps answer the page's central question. Do not force every source into the project's current data model or product vocabulary.
• After editing, confirm that a first-time reader can state the thesis, key evidence, and limits after one pass. Rewrite or remove any passage that adds context without improving that understanding.

Use a direct voice

• State what the object does. Let the reader decide whether it is good.
• Write about the reader's task. Use second person for instructions.
• Use present tense for current behavior. Use past tense for events and history.
• Use first person only when a named person or organization can support the claim.
• Name the exact control, command, limit, state, and outcome.
• Name limits and edge cases. A precise boundary makes the rest of the explanation credible.
• Do not use exclamation marks or all-capital emphasis.
• Remove “simply,” “just,” or “easily” when the word minimizes work or adds no meaning.

Edit without changing meaning

Confirm the meaning before you shorten the prose. Preserve facts, names, numbers, quotations, links, code, commands, and necessary qualifications.

• Delete stock metaphors, similes, and figures of speech.
• Keep a fresh comparison only when it makes a mechanism easier to understand.
• Prefer the shortest familiar word that preserves the exact meaning.
• Keep an established technical term when an everyday substitute would be less precise.
• Delete each word that adds no fact, relationship, tone, or useful rhythm.
• Use active voice when the actor and action matter.
• Use passive voice when the actor is unknown or the result matters more than the actor.
• Replace jargon with plain English when both have the same meaning.
• Define a necessary technical term once. Use the same term after the definition.
• Rewrite a sentence when a word replacement changes the grammar or meaning.

Read the edited paragraph at speaking pace. Restore a transition or exact qualification if compression makes the paragraph mechanical.

Accuracy has priority over a local line-editing rule. Record a recurring exception in the closest canonical guide.

Support each claim

• Give each headline, summary line (dek), callout, and marketing line one concrete claim.
• Replace praise with observable behavior, a boundary, or evidence.
• Treat “revolutionary,” “seamless,” “powerful,” “robust,” and similar words as requests for proof.
• Use the swap test. If an unrelated product could publish the sentence unchanged, make it specific or delete it.
• Remove self-congratulation from release notes, documentation, and product copy.
• State what changed, why it changed, and what the reader can now do.
• Put each qualification beside the claim that it limits.

Use consistent text conventions

• Use sentence case for headings, buttons, tabs, labels, placeholders, and empty states.
• Capitalize proper nouns according to their official form.
• Put periods on full sentences, including callouts.
• Omit periods from headings, buttons, and short labels.
• Use the Oxford comma.
• Use natural contractions when they match the voice. Do not force them.
• Use curly quotation marks in prose and straight quotation marks in code.
• Put literal input and interface values in code.
• Use an ellipsis glyph (…) only when an action opens another input step.
• Do not use em dashes in authored prose. Use parentheses only for a short, necessary explanation.
• Spell out zero through nine in prose. Use numerals for 10 or more, measurements, dates, and money.

Write focused documentation

• Decide whether a page is a tutorial, how-to guide, explanation, or reference.
• Do not mix document modes when a link gives the reader a clearer path.
• Lead with the outcome. Do not write “In this guide, we will.”
• Make headings form a useful path through the page.
• Give each paragraph one main topic. Let the argument determine its length.
• Use numbered steps only for procedures. Start each step with an imperative verb.
• Give one instruction per step. Put a prerequisite condition before its command.
• Use notes, tips, warnings, and danger callouts according to consequence.
• Keep essential information in text. Do not put essential information only in an image or diagram.

Keep interface copy operational

• Do not invent marketing copy to fill space.
• Omit taglines, benefit claims, unsupported proof, and decorative labels unless they help the reader complete a task.
• Use one literal heading for the object, task, data view, or state.
• Add supporting text only for a distinct instruction, constraint, status, or scope.
• Name the action, object, current state, limit, or recovery step.
• Do not narrate the interface or repeat visible information.
• Keep normal readiness silent. Show status text for pending work, important results, or problems that the reader can fix.
• Add search only when the collection is too large or varied for direct selection.
• Move secondary actions and settings out of persistent primary controls.
• Use checkboxes for independent form choices that take effect on submission.
• Use toggle buttons for immediate view, visibility, mute, solo, and mode changes.
• Keep a unit label with its control. Put longer explanations in nearby text or a disclosure.
• Put provenance, tuning, and methodology in a labeled disclosure when they compete with the primary task.
• Use a specific verb and object on buttons. Write “Create project,” not “Submit” or “OK.”
• Use “New noun” to open a creation flow. Use “Create noun” for the committing action.
• Name the missing object in an empty state. Give one useful sentence and the primary action.
• State the problem and the fix in an error. Do not blame the reader or write “Oops.”
• Name the consequence in a confirmation. Repeat the exact verb and object for a destructive action.
• Use nouns for labels. Use placeholders for a format or example, not a repeated label.
• State the completed result in past tense in a toast notification.