Adaptive README Template

This is a decision-oriented guide for public product READMEs, not a mandatory table of contents. It combines recurring reader expectations from the open-source reference catalog with Wisent's stricter requirements for boundaries, operational honesty, security, support, and observable first success.

The catalog does not support one universal long-form structure: its READMEs range from 17 to 941 lines, while architecture appears in 16% and installation or first-use guidance in 76%. Choose the narrowest shape that resolves the actual reader's decisions. Combine, rename, reorder, or omit sections when that improves the route through the document; never omit a decision that is material to safe use.

Every README uses one mandatory opening shell before its adaptable body: a repository-owned product banner is the first rendered element, followed immediately by one compact strip of clickable badge buttons and current product statistics. The product shape still determines everything after that shell.

How to use this guide

1. Verify every current-behavior claim against the repository, released artifact, or operated product.
2. Choose a README shape below from the product's reader and operating model, not its perceived importance.
3. Add the mandatory banner → badge-button and statistics strip, copy the core template, then add only the conditional modules whose trigger is true.
4. Replace every bracketed placeholder and remove every author instruction.
5. Apply the publication gate. It checks reader outcomes, not exact headings, section count, length, tables, or diagrams.

There is no target line count. A short gateway is complete when it routes every reader correctly; a longer operated-product README is complete when it exposes material obligations without becoming a duplicate documentation site.

Choose the narrowest shape

Gateway

Use for a component, contract, internal tool, or non-self-service product whose main reader decision is where it fits and where to continue.

Include:

• product or component identity and its role;
• the owning system and explicit scope boundary;
• the canonical consumption, access, or documentation route;
• maturity, distribution, support, security, and license position.

Do not invent an installation flow, user persona table, architecture diagram, or operational matrix. Link to the owning product's documentation where that is the actual user surface.

Standard product

Use when a person can install, access, or directly use the product.

Include the gateway decisions plus:

• the intended user and promised outcome;
• one complete first-success path or access path;
• supported outcomes and important non-goals;
• proof for the main claim;
• documentation, support, and contribution routes that actually exist.

Operated product

Use when successful use depends on deployment, persistent state, credentials, networking, paid services, upgrades, or recovery.

Start with the standard product shape. Add only the operational concerns that change a reader's adoption or operating decision. Keep procedures in dedicated operations documentation and summarize ownership, prerequisites, and failure boundaries in the root README.

A repository may be technically complex and still need only a gateway. A small repository may need the operated shape if it controls credentials, money, or durable data.

Universal reader decisions

Every README must answer these questions, but the answers may be a sentence, list item, link, command, or dedicated section:

• What is this, for whom, and to what observable end?
• What is supported now, and what important expectation is outside scope or unverified?
• What should the reader do next? Install, try, request access, consume the component, or open the canonical documentation.
• How can the main claim be inspected? Use a real result, current compatibility or release signal, measured evidence, or a maintained product demonstration.
• What is its current status? State maturity, distribution, compatibility when relevant, and whether this repository is the product, a component, a contract, or an internal tool.
• Where do questions, defects, sensitive reports, contribution proposals, releases, and license questions belong? Include only real routes; state an absence rather than inventing one.
• Which external obligations can surprise the reader? Name material credentials, infrastructure, data, network, cost, backup, recovery, or operator ownership.

The first screen begins with the banner and badge-button/statistics strip, then resolves the first and third questions with the product name, a five-to-eight-sentence hook, the primary route, and one decision-relevant trust signal. The rest should follow the reader's likely path: first success, supported scope, deeper documentation, then operations or contribution detail.

Editorial quality bar

Matching the reference catalog's quality does not mean matching its median length or copying its headings. It means reproducing its strongest editorial behavior:

• Immediate comprehension: the first 30 lines carry the mandatory banner, badge buttons, current statistics, identity, a five-to-eight-sentence hook, proof, and the primary route.
• Claim → evidence → action: a capability claim is followed by a result, screenshot, benchmark, example, or source, then by the route for using it.
• Concrete nouns and verbs: name the actor, operation, artifact, environment, and result; remove slogans that could describe another product unchanged.
• Demonstrated first use: show enough setup, invocation, and output for the reader to recognize success without reconstructing missing steps.
• Progressive depth: keep adoption decisions in the root README and route implementation inventories, exhaustive references, and operating procedures elsewhere.
• Purposeful repetition: repeat a command or claim only when the new context changes how the reader uses or evaluates it.
• Maintained surfaces: every screenshot, code sample, link, compatibility statement, and visible version is coupled to the product behavior it documents.

Use the measured length bands as diagnostics, not quotas: 13 of 50 examples are 75 lines or fewer, 21 are 76–200, 7 are 201–400, and 9 exceed 400. The median is 121.5 lines and 947 words. A README above 200 lines should earn the extra space with distinct workflows, environment variants, demonstrations, or contributor material; a README below 75 should still resolve every applicable universal decision.

Before drafting, choose the closest editorial strategy in README Best Practices: compact gateway, standard product guide, workflow-rich guide, or in-repository manual. Copy its pacing and evidence density, not its title structure or length.

Copyable core template

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/readme-banner-dark.png">
  <img src="assets/readme-banner.png" alt="[Product name — specific product outcome]">
</picture>

[![Join Wisent on Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/qRjpkthq54)
[![Release: current value](https://img.shields.io/badge/Release-current_value-2E7D32?style=for-the-badge)]([release-source-url])
[![Current statistic: value](https://img.shields.io/badge/Statistic-current_value-1F6FEB?style=for-the-badge)]([statistic-source-url])

# [Product name]

[A five-to-eight-sentence hook that creates immediate interest in the product. Name the intended user and desired outcome, sharpen the problem or stakes, present the key capabilities as user benefits, explain the product's material differentiator, and bridge directly to the proof and primary action below. Use concrete product-specific claims; do not repeat the title, inventory internal modules, or pad the hook with generic AI slogans.]

[Optional proof placed next to the claim: real screenshot or recording, measured result with method, compatibility statement, or case study.]

## [Get started, Request access, Use this component, or another honest primary action]

[Prerequisites or access boundary, if any.]

```sh
[Smallest copyable and safe action, when the product has a runnable path]
```

[Observable successful result, or the exact state the reader should reach. For a non-runnable gateway, identify the canonical consumer or next document instead.]

## [Capabilities, Scope, or What it does]

- [Supported current outcome]
- [Supported current outcome]
- [Important non-goal, unsupported environment, or constraint]

[Link to examples or deeper documentation rather than inventorying internal modules.]

## [Status, Help, or Project information]

- **Status:** [Maturity and whether this repository is the product, component, contract, or internal tool]
- **Distribution:** [Package, release, application, service, source, or access route]
- **Compatibility:** [Only when a support window or known exclusion affects use]
- **Documentation:** [Canonical route]
- **Questions and defects:** [Correct route]
- **Sensitive security reports:** [Private route; never direct vulnerabilities to a public issue]
- **Contributions:** [Guide or owning-team route when contributions are accepted]
- **License:** [Current license position linked to its text]

The bracketed labels are decisions, not prescribed headings. Merge the scope and status material when each needs only a sentence. Split them when distinct audiences would otherwise miss a material constraint.

Hook

The hook is mandatory and appears directly below the product title without its own heading. Write five to eight sentences in one or two compact paragraphs that make the intended reader want to continue while accurately exposing the product's key capabilities.

Build the hook as a short narrative rather than a feature dump:

1. Open with the reader's desired result or the costly problem the product removes.
2. Make the stakes concrete enough that the reader can recognize their own situation.
3. Present the few key capabilities that produce the result, phrased as benefits rather than internal implementation.
4. State the differentiator, boundary, or reason the product is credible.
5. Close by bridging naturally to nearby proof and the primary action.

Vary sentence length and emphasis so the hook reads as deliberate product copy, not a filled template. Strong language is welcome when the repository, released artifact, operated product, or adjacent evidence can support it; never trade factual accuracy for excitement.

Conditional modules

Audience and alternatives

Add when the opening hook cannot distinguish materially different users, jobs, or alternatives. Prefer a short paragraph or list. Use a table only when readers genuinely need to compare several roles or outcomes.

Supported environments and interfaces

Add when compatibility varies by operating system, runtime, deployment model, API, CLI, SDK, or UI. Name the canonical interface for each operation only when competing interfaces would create ambiguity. A matrix is useful for real comparisons, not as a default form.

How it works

Add when a conceptual model changes adoption, trust, deployment, or failure decisions. Explain the smallest accurate path from intent to result. Include durable state, credential, network, and failure boundaries only when they exist and matter.

A diagram is optional. Use one only when it communicates the model faster than prose; Mermaid is one available format, not a requirement. Keep implementation inventories in architecture documentation.

Operations

Add for the concerns that are prerequisites or material risks:

• configuration and precedence;
• state ownership and retention;
• credential acquisition, storage, rotation, and revocation;
• required network direction and endpoints;
• cost ownership and bounding controls;
• health, logs, metrics, and audit behavior;
• upgrade compatibility, migration, and rollback;
• backup, recovery, and data-loss boundaries.

Do not create an eight-row table merely to say that most concerns do not apply. State the few real obligations compactly and link to the operating guide for procedures.

Community, contribution, and governance

Give these a visible section when community participation or external contribution is an actual product surface. State accepted contribution types, the development route, conduct or governance rules, and the correct discussion channel. A private or closed product may instead name the owning team and escalation route.

Roadmap, acknowledgements, sponsors, adopters, and contents

Add only when they answer a current reader question. Keep plans separate from shipped behavior. Add a table of contents only when heading navigation is no longer sufficient.

Opening banner, buttons, statistics, and other media

The opening shell is mandatory and ordered:

1. Product banner: the first rendered element, with no heading, prose, badge, or sponsor block before it.
2. Badge-button and statistics strip: one compact row of linked badge images immediately below the banner. The reference catalog uses these badges for facts and destinations such as package or release version, downloads or pulls, build and coverage state, supported runtimes, license, product website, documentation, and community channels. Every Wisent product includes the canonical Wisent Discord badge.

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

Each product selects the badges supported by its real distribution and reader needs; there is no universal product-specific set beyond the Wisent Discord route. Every displayed value must be current, unambiguous, and reproducible from its linked canonical source. Prefer dynamic badges for changing values 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. For a private or non-packaged product, use honest facts such as release, compatibility range, supported platform count, or deployment status instead of inventing downloads, users, or popularity.

The catalog supports this opening convention: badges appear in 42 of 50 reference READMEs, commonly combining current facts with website, documentation, and community destinations. Wisent makes the banner and badge strip mandatory so product identity, useful routes, and current trust signals are consistent across repositories; the rest of the media strategy remains claim-driven.

Choose additional media from the claim:

• visible interface state → a real screenshot with the relevant result legible;
• state transition that cannot be understood from before-and-after images → a short real animation;
• CLI or API behavior → a copyable command or request followed by literal output;
• measured performance → a chart beside the claim and a link to method and limitations;
• environment support → a compact compatibility matrix;
• non-obvious trust, network, or state boundary → the smallest useful diagram.

Prefer static evidence when it communicates the same result. Beyond the required opening shell, a diagram, table, screenshot, or animation appears only when it proves or explains a claim.

README media has two non-overlapping producers:

• Animated demonstration → Probierz. Record one real journey with the product's Probierz manifest, then publish the selected recording with probierz readme-gif <video> --out assets/<journey>.gif. Keep the generated .probierz.json sidecar with the review evidence. The converter requires human review for credentials, personal data, production identifiers, sensitive URLs, readability, and a visible final outcome.
• Static product banner → wisent-asset-generator. Generate and verify the repository-owned PNG with the explicit readme-banner format: wisent-asset-generator produce ... --formats readme-banner --export-dir <product>/assets --export-format png. Its format contract is 1584x396; the campaign and references must carry the product's current promise and actual visual identity.

Do not hand-author replacement GIFs or banners when these producers are available. Probierz does not generate static brand compositions, and wisent-asset-generator does not invent or simulate UI journeys.

For animated proof:

• show one complete real outcome, including the decisive action and observable result;
• remove idle time without hiding material waits or failures;
• use synthetic fixtures and remove credentials, personal data, customer identifiers, production URLs, and unrelated chrome;
• keep labels legible, provide specific alt text and an accessible textual or static fallback;
• use a stable repository-owned path and avoid making the repository expensive to clone;
• retain the Probierz provenance sidecar for review and replace or delete stale demonstrations when the visible contract changes.

For a static banner, make it the repository-owned visual identity for the product's current promise, legible in both GitHub color schemes, compressed, and equipped with specific alt text. Regenerate it when the promise or identity changes; never replace it with an unrelated decorative image.

Publication gate

Universal checks

Do not publish until a reviewer can answer yes:

• The first rendered element is the current product banner; the next block is the working badge-button and statistics strip, including the canonical Wisent Discord route; the remainder of the first screen contains the product title, a concrete five-to-eight-sentence hook, nearby proof, and the next action.
• The README states current supported scope and every important non-goal, unsupported environment, or unverified guarantee.
• The primary action is accurate and safe; a runnable path ends in a result the reader can recognize.
• Material claims have nearby, maintainable evidence.
• The opening is understandable without internal project context, and its primary claim follows a claim → evidence → action sequence.
• Current behavior is clearly separated from planned behavior.
• Maturity, distribution, documentation, support, sensitive-reporting, and license positions are current and honest.
• Material credential, data, network, cost, backup, recovery, and operator obligations are visible before they can surprise a reader.
• Every badge button has a real destination, every displayed statistic links to its canonical source, and no value is stale, invented, or ambiguous.
• The document's length is earned by distinct reader decisions, workflows, demonstrations, or routes rather than repeated claims or implementation inventory.
• Every visual uses the medium appropriate to its claim, appears near that claim, has useful alternative text, and remains legible in both GitHub color schemes.
• No secret, personal or production identifier, unsupported claim, or unexplained destructive command appears.

Conditional checks

Apply only when the corresponding trigger is true:

• Multiple audiences or interfaces have distinct outcomes and canonical routes.
• Environment or version differences are explicit where they affect compatibility.
• A conceptual model explains a real adoption, trust, deployment, or failure decision.
• An operated product names ownership for every material operational concern and links to procedures.
• Contribution, community, governance, release, and commercial-support routes match what the project actually offers.
• Every demonstration came from a real product journey, retains its review provenance, contains no sensitive data, remains accessible, and matches the current release.

Completeness is the absence of unresolved reader decisions, not the presence of nine headings. No reviewer may reject a concise README for omitting a section, table, or diagram whose underlying decision is already answered or does not apply.