README Guidelines

The README is the first product artifact. It defines what the product is before release mechanics, onboarding, implementation, integrations, examples, or verification artifacts are created.

A README is not a retrospective inventory of whatever the code happens to do. It is the product contract against which later work is evaluated. That contract is defined by resolved reader decisions, not a fixed heading list.

The body structure is adaptive, but the opening shell is not: every README begins with a product banner followed by one compact strip of clickable badge buttons and current product statistics.

Required outcome

After reading the README, an intended user or consuming system must understand:

• what the product is, who it is for, and what observable outcome it delivers;
• why the product is meaningfully different from the current alternative when that decision is not obvious;
• what is supported now and what important expectation is outside scope or unverified;
• how to install, access, consume, or continue to the canonical documentation;
• what successful use looks like when a runnable path exists;
• which prerequisites and external obligations can affect safety, cost, data, or recovery;
• the product's maturity, distribution, support, security-reporting, and license position;
• where to find deeper user, operational, and technical documentation.

The answer may be concise. A sentence or link satisfies a decision when it is precise, current, and discoverable; a dedicated section does not satisfy it when its content is vague.

First-screen gate

Every README must begin in this exact rendered order:

1. Product banner: a repository-owned banner is the first visible element. Nothing—not the # heading, prose, badges, or sponsor content—appears before it.
2. Badge-button and statistics strip: linked badge images show useful product destinations and current product facts. Common examples are website, documentation, Discord or another maintained community channel, package or release version, downloads or pulls, default-branch build, coverage, compatibility, supported platforms, and license. Every Wisent product includes a badge linked to the canonical Wisent Discord.

A plain Markdown link, table-of-contents entry, or link to a section in the same README is not a button. A button is a rendered badge image inside a link, normally an <a><img></a> pair or equivalent linked-image Markdown.

There is no fixed product-specific badge set. Include only destinations and facts that apply to the product. Every button must resolve to a maintained destination, and every displayed statistic must be current, unambiguous, and reproducible from the linked canonical source. Prefer dynamic badges only when the badge service can read that source. External GitHub metadata badges cannot read private repositories and render repo not found; use a source-backed static badge linked to the canonical private source, or a public first-party metrics endpoint, and update the displayed value with its source change. A repository without public downloads or adoption metrics must use honest product facts instead of inventing popularity.

After that shell and before the first substantial scroll, an intended reader must also be able to identify:

• the canonical product or component;
• the outcome it delivers and for whom or for which owning system;
• one decision-relevant reason to trust the claim;
• the next action: try, install, request access, use the component, inspect documentation, or contact the owner.

The banner establishes product identity; it does not replace the textual name, promise, or accessible alternative text. The badge strip must remain compact enough that it does not push the product outcome and next action below the first screen.

Required decisions, adaptable structure

Every README must resolve the decisions below. It must not copy nine headings merely to prove compliance.

Identity, audience, and outcome

Start with the canonical name and a precise promise. Name the intended user or consuming system and the observable result. Avoid internal project names, implementation-first descriptions, and generic claims such as “powerful,” “modern,” or “easy to use.”

A separate audience or problem section is required only when the opening cannot distinguish materially different users, pains, or alternatives.

Current scope and boundaries

State supported current outcomes and every non-goal, unsupported environment, unverified guarantee, or operator responsibility that could change adoption or safe use. Planned work must be visibly separate from shipped behavior.

Boundaries may be prose, bullets, a compact comparison, or a dedicated section. Do not add an empty taxonomy of “included,” “not included,” and “supported environments” when one direct sentence is clearer.

Primary action and first success

Provide the shortest honest route for the product's actual delivery model:

• a self-service product shows prerequisites, a copyable safe action, and a result the reader can recognize;
• a hosted or approval-gated product shows the access route and what happens after access;
• a component shows the canonical consumer, interface, or integration documentation;
• an internal tool names the owning system and operating route.

Do not invent a local quick start for a product that cannot be run locally. Do not present installation alone as successful use. Keep production credentials and destructive defaults out of introductory paths.

Proof

Place maintainable evidence next to material claims. Acceptable evidence includes:

• a real screenshot or product journey;
• a benchmark linked to its method and limitations;
• a compatibility matrix;
• a current CI workflow signal;
• an architecture diagram that explains a boundary;
• an adopter or case-study link;
• a literal or clearly described successful result.

Visuals must prove, explain, or establish product identity. The opening banner and badge-button/statistics strip are mandatory; every other visual is claim-driven. Unsupported superlatives, decorative screenshots, dead buttons, unlinked or invented statistics, and unrelated badge walls are prohibited.

Status, trust, and reader routes

State maturity and distribution. Add compatibility when versions or environments affect use. Make the documentation, support, defect, private security-reporting, contribution or owner, release, and license positions discoverable.

A route must exist. If the repository lacks a contribution guide, security policy, release channel, or license, state the current position instead of inventing an address or linking to a generic destination.

Choose the README shape

Use the Adaptive README Template and choose the narrowest applicable shape:

• Gateway: component, contract, internal tool, or non-self-service surface. Resolve identity, role, scope, canonical continuation route, and status.
• Standard product: directly usable product. Add first success, supported outcomes, important boundaries, proof, and real reader routes.
• Operated product: product with deployment, persistent state, credentials, networking, paid dependencies, upgrades, or recovery. Add only the material operational contracts.

These are decision profiles, not size or prestige levels. A complex internal component may need a short gateway; a small credential broker may require the operated shape.

Conditional disclosures

Add detail when its trigger is true:

• Multiple audiences: distinguish their starting situations and successful outcomes.
• Multiple public interfaces: name the canonical interface for each class of operation and link its lifecycle, authentication, errors, compatibility, and examples.
• Environment differences: state supported operating systems, runtimes, deployment models, and known exclusions.
• Non-obvious product model: explain the smallest accurate path from intent to result and the relevant trust or failure boundaries.
• Operated state: summarize material configuration, state, credentials, networking, cost, observability, upgrades, recovery, and ownership; omit concerns that genuinely do not apply.
• Public participation: expose contribution, community, conduct, and governance routes.
• Plans: label roadmap material and keep it separate from current behavior.

A table is appropriate for a real comparison or matrix. A diagram is appropriate when it communicates a model faster than prose. Neither is a completion requirement.

Progressive disclosure

Minimize time-to-understanding without hiding obligations. Prefer this reader sequence:

1. mandatory banner and badge-button/statistics strip; then promise, audience, proof, and primary action;
2. first success or canonical continuation route;
3. supported outcomes and material boundaries;
4. deeper documentation, status, support, and contribution routes;
5. architecture or operations only when they affect adoption or safe use.

Length is not a quality target. Use the shortest structure that resolves the reader's next decisions. Add a table of contents only when scanning headings is no longer efficient. Keep detailed architecture and operating procedures outside the root README unless they are prerequisites or explain user-visible behavior, trust, cost, or failure.

Route readers by intent

A root README is a map, not a duplicate documentation site. Distinguish destinations for:

• learning and using the product;
• operating or self-hosting it;
• reporting a reproducible defect;
• asking for help;
• proposing a change;
• reporting a vulnerability privately;
• understanding releases, compatibility, and license terms.

Combine routes when one destination genuinely owns several intents. Do not expose an undifferentiated link list or duplicate detailed procedures to make the README appear complete.

Writing rules

• Write for the intended user or consuming system, not for the implementation team.
• Lead with outcomes and constraints; introduce architecture only when it explains behavior.
• Use one canonical term for each product concept.
• Keep commands realistic and internally consistent.
• Separate current behavior from planned behavior.
• Make material safety, cost, credential, and data-loss boundaries explicit.
• Link to detailed documents instead of duplicating them.
• Prefer concrete examples over slogans.
• Use descriptive headings in the reader's language; do not number sections to satisfy a template.

Prohibited patterns

A README must not:

• begin with installation before explaining what is being installed and for whom;
• present an unstructured feature or module inventory as the product definition;
• claim integrations, environments, or guarantees that are not supported;
• hide mandatory setup or material risk in another document;
• rely on tribal knowledge;
• use screenshots as the only explanation of a workflow;
• include secrets, real credentials, personal data, or production identifiers;
• publish an introductory workflow that stops before the reader can recognize success;
• describe implementation trivia with no user-visible consequence;
• add tables, diagrams, personas, operational rows, or boilerplate sections solely because the template contains them;
• treat absence of a heading as absence of the underlying decision;
• show a dead or ambiguous button, an unlinked statistic, an invented metric, or a value that is no longer current.

Evidence base

The README Best Practices derive reusable patterns from the curated open-source README catalog. Exact structural measurements are recorded in the generated analysis.

The 50-snapshot catalog spans 17 to 941 lines, with a median of 121.5 lines and 947 words. Twenty-six percent are 75 lines or fewer, 42% are 76–200, 14% are 201–400, and 18% exceed 400. Installation or first-use guidance appears in 76%, contribution guidance in 78%, support or community routes in 76%, documentation links in 66%, and architecture or “how it works” material in 16%. These measurements support progressive disclosure and adaptable shapes, not one mandatory outline.

Visual syntax appears within the first 30 lines of 98% of the catalog, and badges appear in 84%. Wisent turns that strong opening convention into a stricter product shell: every README has a maintained banner and a compact strip of linked badge buttons and source-backed statistics, including the canonical Wisent Discord route. Code examples still appear in 64%, animated GIFs in 6%, embedded video in 0%, Mermaid in 0%, and Markdown tables in 16%; those additional media remain conditional.

Catalog prevalence is evidence of reader convention, not proof of quality. Wisent keeps current boundaries, material operator obligations, maturity, private security reporting, support, and license position mandatory even where popular repositories omit them.

Change discipline

Any change to the product promise, intended audience, supported outcomes, public interfaces, environments, safety boundaries, or operating obligations must update the README first.

That README change triggers review of affected downstream documents and implementation in dependency order. Reopen only the stages whose decisions changed; do not rewrite unrelated documentation to preserve superficial template symmetry.

Completion gate

The README stage is complete only when:

• the mandatory banner → badge-button and statistics strip order is present and the remainder of the first-screen gate passes;
• every universal reader decision is resolved;
• every triggered conditional disclosure is present and current;
• the primary action matches the real delivery model and reaches a recognizable destination;
• current and planned capabilities are clearly separated;
• all terminology and reader routes are consistent;
• later stages can proceed without inventing product scope or operational obligations;
• no body section, table, diagram, badge, or additional media asset exists solely to satisfy a template; the mandatory opening assets each carry current identity, a maintained destination, or source-backed evidence.