Writing README
Opening sections, section order, installation steps, quick start, and badges
README essentials
- Opening: Name + one-line description + the problem it solves — answer "what is this and who needs it?"
- Order: Description → Installation → Quick start → Configuration → Contributing → License
- Installation: exact commands + prerequisites + expected output — testable by a new developer
- Quick start: minimal working example — copy, paste, run in under 2 minutes
- Useful badges: CI status, version, license — skip decorative or vanity badges
Question 0 of 5
Which README opening section is most effective for an open-source library?
Name + one-line description + the problem it solves is the strongest README opener. README opening formula:
- Name: "dbmigrate" — displayed as the heading
- What it is: "zero-downtime PostgreSQL migration runner in Go" — category + technology
- The pain it solves: "Run schema migrations without table locks on databases with millions of rows" — immediately answers "why should I use this?"
Which README section order is most effective for an open-source project?
What → Install → Use → Configure → Contribute → License follows the reader's journey. Why this order works:
- Description: Is this for me? (should I keep reading?)
- Installation: How do I get it? (fastest path to value)
- Quick start/Usage: Does it work? (first success = retention)
- Configuration: How do I customise it? (after the first success)
- Contributing: How do I help? (only relevant after they already use it)
- License: Can I use this commercially? (last check before adopting)
A README contains this installation section: "Install the dependencies and run the project." What is missing?
Exact commands + prerequisites + expected output. Complete installation section:
- Prerequisites: "Requires Go 1.22+ and PostgreSQL 14+"
- Install command:
go install github.com/acme/dbmigrate@latest - Verify install:
dbmigrate --version→ expected output:dbmigrate v1.4.2 - First run:
dbmigrate init --dsn "postgres://user:pass@localhost/mydb"
What is the purpose of a "Quick Start" or "Usage" code example in a README?
Minimal working example — copy, paste, run in under 2 minutes. Quick start principles:
- Show the 80% use case — the thing most people will do first
- The example should actually work — test it
- Minimal configuration — don't require 5 setup steps before the first line of real usage
- Annotate the non-obvious parts with inline comments
- Not an exhaustive options list (that's the configuration section)
- Not an architecture explanation (that's the "How it works" section)
- Not a tutorial with multiple chapters
Which badge is most useful to include at the top of an open-source README?
CI build status — actionable information for contributors. Useful README badges:
- ✅ CI status: "build passing" / "build failing" — contributors check before PRs
- ✅ Latest version: npm/Go/PyPI version badge — developers check compatibility
- ✅ License: MIT/Apache/GPL — licensing clarity upfront
- ✅ Code coverage: shows test quality signal
- ✅ Downloads/week: social proof of adoption
- ❌ "Made with ❤️" — tells contributors nothing useful
- ❌ Profile view counters — vanity metric, no value to library users