README Best Practices from the Reference Catalog

This document turns the curated open-source README examples into practical guidance for Wisent repositories. It complements the normative README Guidelines: the catalog shows effective public patterns, while the guidelines define the higher trust and completeness standard required for Wisent products.

Evidence and method

The reference catalog contains fifty verbatim snapshots across applications, frameworks, libraries, command-line tools, databases, infrastructure, observability, and AI systems. The reproducible structural analysis measures document length, headings, visuals, code examples, and recurring reader routes. The qualitative review covered contrasting approaches from Supabase, Kubernetes, Prometheus, Ollama, FastAPI, uv, and bat.

Structural prevalence is not proof of quality. A section can exist and still be vague, while a concise README can satisfy an outcome without using a conventional heading. The practices below therefore combine measured recurrence with close reading and Wisent's operational requirements.

What the catalog showed

• Visual syntax appears in 49 of 50 READMEs and in the first 30 lines of the same 49. The common pattern is to establish identity or show proof before deep explanation.
• Badges appear in 42 of 50, usually for release, compatibility, build health, community, or license signals. This records catalog convention; Wisent deliberately permits only the canonical default-branch CI badge.
• Code examples appear in 32 of 50. Installation or first-use guidance appears in 38, contribution guidance in 39, support or community routes in 38, and documentation links in 33.
• Explicit security guidance appears in 14, status or roadmap material in 12, and root-level architecture or “how it works” material in 8. Popularity therefore does not make these obligations safely inferable.
• Rich media is much less common than static imagery: 3 READMEs reference an animated GIF, none embeds video, and none uses Mermaid.
• Markdown tables appear in 8 and a table of contents in 5. Both are tools for real comparison or navigation, not default signs of completeness.

These observations explain common reader expectations. They do not lower Wisent's requirements where the public sample is incomplete.

Best practices

Make the first screen a product decision

Before the first substantial scroll, a reader should see:

• the canonical product name;
• one sentence naming the user outcome;
• one concrete reason to trust the claim;
• the next action: try, install, inspect documentation, or request access.

uv pairs a precise promise with a benchmark and supported platforms. FastAPI combines a short promise, package and compatibility signals, and direct documentation links. Ollama moves from a minimal promise directly to download and first use. The common strength is not visual polish by itself; it is low time-to-understanding.

Wisent READMEs may show at most one badge: the canonical default-branch CI workflow status, linked to that workflow. Release, compatibility, license, downloads, funding, and community remain contextual text links. A badge wall must not displace the promise or primary action.

Use progressive disclosure

Strong READMEs usually move through this sequence:

• promise and audience;
• proof or differentiator;
• shortest successful path;
• supported capabilities and boundaries;
• deeper documentation, operations, support, and contribution routes.

The catalog ranges from very short project gateways to extensive product manuals. The median is around one hundred twenty lines and roughly one thousand words, but length is not a target. The correct length is the shortest document that resolves the reader's next decisions without hiding mandatory setup or risk.

A table of contents is uncommon and should be added only when navigation cost justifies it. Detailed architecture is also uncommon in the root document; include it only when it explains user-visible behavior, deployment, trust, or failure boundaries.

Let reader value earn the length

The catalog's length distribution is broad:

Observed band	Catalog count	What earns the space
Compact, 75 lines or fewer	13 (26%)	One product decision, a gateway to canonical docs, or a small surface with few obligations
Standard, 76–200 lines	21 (42%)	Promise, supported outcomes, first use, routes, and concise trust boundaries
Extended, 201–400 lines	7 (14%)	Several distinct workflows, installation variants, or decision-relevant operating detail
Manual-like, over 400 lines	9 (18%)	A broad CLI, library, or platform whose examples remain useful in repository context

The median is 121.5 lines, 947 words, 11 headings, and 1.5 fenced code blocks. These are reference points, not targets. Diagnose a README below 75 lines for missing decisions and one above 200 for content that belongs in dedicated documentation; keep either length when every omission or retained section is justified by the product.

Long examples are not padded versions of short ones. Their extra space is earned by executable examples, platform-specific installation, visible capability demonstrations, integrations, or contributor routes. Repeated promises, internal module inventories, and empty operational rows do not earn length.

Match the README shape to the reader decision

The catalog does not converge on one outline. Its documents range from short gateways to extensive operating manuals, and architecture or “how it works” material appears in only 16%. Treat section names as editorial choices, not evidence of completeness.

Choose the narrowest applicable shape:

• a gateway identifies a component or controlled product, its scope, owning system, canonical continuation route, and status;
• a standard product README adds first success, supported outcomes, proof, boundaries, and reader routes;
• an operated-product README adds only the deployment, state, credential, network, cost, upgrade, and recovery contracts that materially apply.

Do not infer the shape from repository size or product importance. Use the reader and operating model. Resolve a simple decision in a sentence rather than creating a table, and introduce a diagram only when it communicates a non-obvious model faster than prose.

Show one complete happy path

Installation alone is not a quick start. A useful path contains:

• prerequisites;
• a copyable installation or access step;
• the smallest realistic invocation;
• an observable expected result;
• a safe next step.

FastAPI is exemplary: create, run, check, see the response, then inspect generated documentation. The expected output closes the loop and proves that the reader reached a working state. Wisent quick starts must follow the same pattern and must avoid production credentials or destructive defaults.

Put proof next to the claim

Prefer evidence that a reader can inspect:

• a screenshot showing the promised outcome;
• a benchmark linked to its method and limitations;
• a compatibility matrix;
• a release or build signal;
• an architecture diagram that explains a boundary;
• an adopter or case-study link;
• a literal expected command result.

Do not use screenshots as decoration or badges other than the canonical CI signal. Unsupported superlatives, unqualified performance claims, and stale status indicators reduce trust.

Use the medium that proves the claim

The reference set is visually front-loaded but predominantly static. Effective patterns include:

• a restrained logo or product image that establishes identity without displacing the promise;
• a benchmark graphic immediately beside a measured performance claim, as in uv;
• one static screenshot beside each visible capability, as in bat;
• a copyable code-and-output sequence for a developer product, as in FastAPI;
• light and dark variants when one asset would become illegible.

Choose the medium from the claim: screenshot for visible UI state, terminal transcript for CLI behavior, benchmark chart for measured comparison, compatibility matrix for environment support, diagram for a non-obvious boundary, and animation only for a transition that a static before-and-after cannot explain.

Animations are exceptional in the catalog, not the default quality bar. A GIF must show one real, short outcome and remain understandable through alt text and a static or textual fallback. Embedded video has no precedent in the 50 snapshots and should remain in product documentation or a linked demonstration unless the root README has a concrete reason to carry it.

Treat code as demonstration, not decoration. A short example should include enough setup to run, the decisive action, and the resulting output or state. Longer examples belong in the canonical examples catalog and should be linked from the README.

Route readers by intent

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

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

Supabase explicitly separates community discussion, defects, commercial support, and social chat. Kubernetes separates product use, development, support, governance, adopters, and roadmap. Each route tells the reader what belongs there.

State boundaries and maturity explicitly

Popular projects often rely on external reputation to fill gaps. Wisent products cannot. Every README must make the following discoverable:

• what is supported now and which important expectations are outside scope;
• whether the repository is a product, component, contract, or internal tool;
• the maturity and distribution channel;
• the support, private security-reporting, and license position.

Environment, credential, state, network, cost, upgrade, and recovery detail becomes mandatory when it changes adoption, safe use, or operator responsibility. Do not create a full operational matrix for concerns that do not apply; do not hide a material obligation merely to keep the README short.

Security and maturity sections are not prevalent in the reference set. That is a catalog finding, not a pattern to copy. Wisent keeps the underlying decisions mandatory because its products control agents, infrastructure, credentials, data, and paid entitlements. The decisions may be expressed without dedicated headings when they remain precise and discoverable.

Keep capability lists outcome-oriented

Feature lists work when they help a reader decide whether the product solves the problem. Group them around user outcomes and link each item to proof or documentation. Avoid inventories of internal modules, dependencies, or planned integrations.

Supabase's opening list works because every capability is recognizable to a user and most entries link directly to documentation. bat's feature sections work because they show the visible behavior and then demonstrate real integrations.

Treat contribution and community as product surfaces

Most catalog entries provide a contribution route, support route, or both. These are not footer formalities. They determine whether defects reach the right channel and whether contributors can act without private context.

A public repository should make contribution, support, security reporting, and governance discoverable. A private repository should still name the owning team and the internal escalation route.

Resist cargo-cult README design

Do not copy a pattern merely because it is common:

• visuals are valuable only when they prove or explain something;
• the canonical CI badge is valuable only when current and linked to its workflow;
• a long README is not more complete by default;
• a short README is not clearer if it omits prerequisites or boundaries;
• installation-first ordering is wrong when the reader still does not know what is being installed;
• popularity does not excuse missing security, support, status, or license information.

Copy an editorial strategy, not a section list

The strongest examples solve different reader problems:

• shadcn/ui uses 17 lines as a true gateway: promise, hero, documentation, contribution, and license.
• React uses 78 lines to move from a one-line definition through three outcome-oriented capabilities, adoption routes, one complete example, and contribution guidance.
• Kubernetes uses 100 lines to split “use the product” from “develop the product,” then routes support, community, adopters, governance, and roadmap.
• uv uses 326 lines because its benchmark, platform-specific installation, and several complete workflows help readers choose and adopt the tool.
• FastAPI uses 541 lines to teach create → run → check → inspect documentation as one uninterrupted first success.
• bat uses 941 lines as an in-repository product manual, pairing capabilities with screenshots and executable integrations.

Select the closest strategy by reader task and product surface. Reuse its pacing—what appears before first use, how proof follows claims, when detail moves to a link—not its headings, tone, badge count, or length.

How catalog evidence becomes a Wisent standard

The catalog establishes reader conventions, not a universal document skeleton:

• installation or first-use guidance appears in 76% of the snapshots;
• contribution guidance appears in 78%;
• support or community routes appear in 76%;
• documentation links appear in 66%;
• architecture or “how it works” material appears in 16%;
• documents range from 17 to 941 lines, with a median of 121.5.

These measurements justify a prominent primary action, visible reader routes, progressive disclosure, and no target length. They do not justify forcing every repository to carry the same named sections, tables, diagrams, personas, interface matrix, or eight-concern operating table.

Wisent adds trust decisions that public projects often leave implicit: current scope, material non-goals, maturity, operator obligations, private security reporting, support, and license position. The README Guidelines require those decisions while the Adaptive README Template provides gateway, standard-product, and operated-product shapes.

The standard is therefore stricter about honesty and more flexible about form. A reviewer evaluates whether readers can decide and act safely, not whether the README resembles the template.

Review checklist

A reviewer should be able to answer yes to each applicable question:

• Can the intended user or consuming system identify the product, outcome, and primary action from the first screen?
• Does the primary action match the real delivery model and reach a result or canonical continuation route?
• Is every material claim supported by nearby evidence or a source?
• Are current capabilities separated from plans, and are important non-goals or unsupported environments explicit?
• Are material credential, state, network, cost, upgrade, recovery, and operator obligations visible?
• Can readers find documentation, support, defect, private security-reporting, contribution or owner, release, and license information by intent?
• Does every visual, table, diagram, and section earn its space?
• Is the optional badge, if present, the current canonical default-branch CI workflow status?
• Is the chosen gateway, standard-product, or operated-product shape the narrowest one that resolves these decisions?
• Can downstream implementation proceed without inventing product requirements?