Scrolls
5 min read
On this page

The 30-Second README

A developer lands on your repository. They have a problem to solve and a dozen tabs open with competing projects. Within 30 seconds, they will decide whether your project is worth their time or whether they click the back button. That 30 seconds is all you get. Your README is not a comprehensive manual. It is a pitch, a proof, and an on-ramp — in that order.

The 30-Second Window

Thirty seconds is not a metaphor. It is roughly what eye-tracking studies and analytics show for the average time spent on a repository page before the decision to stay or leave. In that window, the developer is asking three questions, in this order:

Second 0-10:  What does this thing do?
Second 10-20: Can I use it? (Language, license, maintenance status)
Second 20-30: Show me it working.

If any of these questions goes unanswered, you lose the reader. Not because they are impatient, but because there are ten other projects that answer these questions faster.

The Opening Lines

The first two lines of your README are the most valuable real estate in your entire project. They appear in GitHub search results, package manager listings, and social media previews.

Bad opening:

  # MyProject
  ## Introduction
  MyProject was started in 2019 as a way to explore some ideas I had
  about data processing. Over time, it evolved into something more
  general-purpose...

Good opening:

  # csvq
  SQL queries on CSV files. No database required.

  csvq "SELECT name, age FROM ./users.csv WHERE age > 30"

The good opening does three things in three lines: names the project, describes what it does in one sentence, and shows it working. The developer now knows everything they need to decide if this is relevant to their problem.

The One-Sentence Description

Force yourself to describe your project in a single sentence. Not a paragraph. Not a clause-laden monstrosity with semicolons. One sentence.

Bad:
  A highly performant, scalable, cloud-native event-driven microservice
  framework for building distributed systems with first-class support
  for multiple protocols and extensible middleware pipelines.

Good:
  A CLI tool that converts Markdown files to static websites.

Bad:
  An innovative solution leveraging cutting-edge technology to
  revolutionize the way teams collaborate on documentation.

Good:
  Real-time collaborative editing for Markdown, like Google Docs
  but self-hosted.

If you cannot say it in one sentence, you do not understand your own project well enough.

The Install

After the "what," the next thing a developer needs is the "how do I get this." The install instructions should be one command, two at most.

Good install section:

  ## Install
  pip install csvq

  Or with Homebrew:
  brew install csvq

Bad install section:

  ## Installation
  ### Prerequisites
  First, ensure you have Python 3.8 or later installed. You can
  verify this by running python3 --version. You will also need
  pip, which usually comes with Python but may need to be
  installed separately on some systems...

The bad version buries the install command under prerequisites that belong in a separate document. The README install should be the happy path. Link to a detailed installation guide for edge cases.

The Example

Show it working. Not in theory, not in a bulleted feature list, but in actual usage. The example should be copy-pasteable and produce visible output.

Good example:

  ## Usage

  csvq "SELECT name, count FROM ./data.csv ORDER BY count DESC LIMIT 5"

  Output:
  name     | count
  ---------|------
  Alice    | 47
  Bob      | 38
  Charlie  | 29

Bad example:

  ## Usage
  See the examples/ directory for usage examples, or read the
  full documentation at docs.example.com.

The bad example makes the developer leave the README to understand the project. Most will not bother.

Feature Lists vs Working Examples

Feature lists are marketing. Working examples are proof. Lead with examples, follow with features.

Weak:
  ## Features
  - Fast parsing
  - Multiple output formats
  - Plugin system
  - Cross-platform support

Strong:
  ## Quick examples

  Convert Markdown to HTML:
    mdtool convert README.md --format html

  Convert an entire directory:
    mdtool convert docs/ --format html --output site/

  Use a custom template:
    mdtool convert README.md --template my-template.html

The feature list tells you what the project claims. The examples show you what it does.

Above the Fold

"Above the fold" is a newspaper term for what you see before unfolding the paper. In a README, it is what you see before scrolling. Everything critical goes here.

Above the fold (no scrolling required):
  1. Project name
  2. One-sentence description
  3. Install command
  4. One working example with output
  5. Badges (build status, version, license) -- optional but useful

Below the fold (scroll for more):
  6. More examples
  7. Configuration
  8. Contributing guide
  9. License details
  10. Links to full documentation

If a developer has to scroll to learn what your project does, you have already failed the 30-second test.

Badges

Badges communicate project health at a glance. Use them sparingly and honestly.

Useful badges:
  - Build status (passing means it works)
  - Latest version (tells me it is maintained)
  - License (tells me if I can use it)
  - Test coverage (tells me it is tested)

Useless badges:
  - "PRs welcome" (this is true of every open project)
  - Download counts (vanity metric)
  - Five different CI badges for the same build
  - Badges for obvious things ("written in JavaScript")

A wall of badges signals insecurity, not quality. Three or four meaningful badges are plenty.

The Brutal Truth About Attention

Developers evaluating a project are not reading your README. They are scanning it. They look at:

What developers actually look at:
  1. The title and first sentence
  2. Code blocks (eyes jump to monospaced text)
  3. Headings (scanning for "Install" or "Usage")
  4. The age of the last commit (is this maintained?)
  5. Star count and contributor count (social proof)
  6. License

What developers skip:
  1. Long paragraphs of motivation
  2. History of the project
  3. Your architectural philosophy
  4. Detailed comparisons with competitors
  5. Anything that requires reading more than 3 sentences in a row

This is not a criticism. It is a design constraint. Write for scanners, not readers.

READMEs for Different Audiences

Not every README serves the same audience, and the 30-second calculus changes accordingly.

Open source library:
  Audience: Developers evaluating whether to add a dependency
  30-second answer: What does it do, how do I install it, show me code

Internal tool:
  Audience: Coworkers who were told to use this
  30-second answer: What does it do, how do I set it up, who owns it

Framework/platform:
  Audience: Developers making a significant technology choice
  30-second answer: What does it do, who uses it, show me the simplest app

Data project:
  Audience: Researchers or analysts
  30-second answer: What data, what format, how to access it, citation info

Common Pitfalls

  • Leading with motivation — "I built this because..." belongs in a blog post, not the first paragraph of a README. Lead with what it does, not why you built it.
  • No working example — a README without a code example is a product without a demo. The example is not optional.
  • Install instructions that require a PhD — if installing your tool requires more than two commands, your install process is the problem, not the README.
  • Feature lists without proof — "blazing fast" means nothing without a benchmark. "Simple API" means nothing without a code sample. Either prove it or cut it.
  • Outdated examples — an example that does not work is actively harmful. It tells the developer your project is abandoned. Test your README examples.
  • Wall of text before any code — developers scan for code blocks. If the first code block is below the fold, most developers will never see it.
  • README as the only documentation — the README is the entry point, not the destination. Keep it short and link to full docs for everything that does not serve the 30-second decision.

Key Takeaways

  • You have 30 seconds. Answer three questions: what does it do, how do I install it, show me it working.
  • The first two lines are the most important text in your project. One sentence that describes what the project does.
  • Show a working, copy-pasteable example with output above the fold.
  • Write for scanners, not readers. Code blocks, short headings, no walls of text.
  • Everything that does not serve the 30-second decision belongs below the fold or in a separate document.
  • Test your README examples. An outdated example is worse than no example.