Honest README
A README exists to answer three questions fast: what is this, how do I run it,
and how do I use it. Most AI-written or template READMEs bury those under a hero
of badges, a tagline like "Blazingly fast, production-ready, developer-first
toolkit", and a "Features" list where every bullet is an adjective. That styling
reads as generated, and worse, it tells the reader nothing.
The rule: every line earns its place by informing the reader. If a sentence would
be just as true of a hundred other projects, cut it or make it specific.
Cut these
- Superlatives and hype: "blazingly fast", "lightning-fast", "powerful",
"robust", "seamless", "elegant", "production-ready", "battle-tested",
"enterprise-grade", "next-generation". Either show the claim (a benchmark
number, a real constraint) or drop it.
- Badge spam: a wall of shields.io badges for every CI, coverage, license,
downloads, and "made with love". Keep at most the few a maintainer actually
checks (build status, version, license). Decorative badges go.
- Emoji-prefixed headings:
## 🚀 Features, ## ✨ Installation. Plain
headings. (If you want an icon in a hosted doc, see prefer-icons.)
- Vague feature lists: "Fast. Simple. Flexible. Modern." A reader cannot act
on these. Replace with what the thing actually does.
- Filler intros: "In today's fast-paced world of software development...".
Start with what the project is.
Write these instead
- One plain sentence up top that says what it is and who it is for: "A CLI
that converts Figma frames to React components." No tagline gymnastics.
- A real install line people can copy:
npm install x, pip install x.
- A minimal usage example that actually runs, with real-looking input and
output, not pseudo-code.
- Specific, true claims. Not "highly configurable" but "configured through a
single
config.toml; see the options below."
- Requirements and limits if they matter: supported versions, platforms, the
one thing it deliberately does not do.
Before and after
Before:
# ⚡ TurboParse
> 🚀 A blazingly fast, production-ready, developer-first parsing toolkit.
[badge][badge][badge][badge][badge]
## ✨ Features
- Fast
- Simple
- Flexible
- Modern
After:
# TurboParse
Parses large CSV files into typed records, streaming, without loading the whole
file into memory.
## Install
npm install turboparse
## Usage
... a short example that runs ...
Before you deliver
Read the README top to bottom as a stranger. For each line ask: does this tell me
something specific and true, or is it decoration? Cut every adjective you cannot
back up, every badge a maintainer would not check, and every emoji on a heading.
What remains should let someone install and use the thing in under a minute.
For the sentence-level fluff inside the prose, pair this with no-filler-phrases,
no-em-dashes, and no-fancy-ascii.
1---2name: honest-readme3description: Write READMEs and project docs that describe what the thing is and how to run it, without marketing fluff or badge spam. Use this WHENEVER you create or edit a README, a repo description, a docs landing page, or a package summary. Superlatives ("blazingly fast", "production-ready", "powerful", "seamless"), rows of decorative badges, emoji-prefixed headings, and a "Features" list of vague adjectives are the tell that a model or a template wrote it. Replace them with a plain one-line description, a real install and usage example, and claims that are specific and true. Pair with no-filler-phrases for the prose.4---56# Honest README78A README exists to answer three questions fast: what is this, how do I run it,9and how do I use it. Most AI-written or template READMEs bury those under a hero10of badges, a tagline like "Blazingly fast, production-ready, developer-first11toolkit", and a "Features" list where every bullet is an adjective. That styling12reads as generated, and worse, it tells the reader nothing.1314The rule: every line earns its place by informing the reader. If a sentence would15be just as true of a hundred other projects, cut it or make it specific.1617## Cut these1819- **Superlatives and hype:** "blazingly fast", "lightning-fast", "powerful",20 "robust", "seamless", "elegant", "production-ready", "battle-tested",21 "enterprise-grade", "next-generation". Either show the claim (a benchmark22 number, a real constraint) or drop it.23- **Badge spam:** a wall of shields.io badges for every CI, coverage, license,24 downloads, and "made with love". Keep at most the few a maintainer actually25 checks (build status, version, license). Decorative badges go.26- **Emoji-prefixed headings:** `## 🚀 Features`, `## ✨ Installation`. Plain27 headings. (If you want an icon in a hosted doc, see `prefer-icons`.)28- **Vague feature lists:** "Fast. Simple. Flexible. Modern." A reader cannot act29 on these. Replace with what the thing actually does.30- **Filler intros:** "In today's fast-paced world of software development...".31 Start with what the project is.3233## Write these instead3435- **One plain sentence up top** that says what it is and who it is for: "A CLI36 that converts Figma frames to React components." No tagline gymnastics.37- **A real install line** people can copy: `npm install x`, `pip install x`.38- **A minimal usage example** that actually runs, with real-looking input and39 output, not pseudo-code.40- **Specific, true claims.** Not "highly configurable" but "configured through a41 single `config.toml`; see the options below."42- **Requirements and limits** if they matter: supported versions, platforms, the43 one thing it deliberately does not do.4445## Before and after4647Before:48```49# ⚡ TurboParse5051> 🚀 A blazingly fast, production-ready, developer-first parsing toolkit.5253[badge][badge][badge][badge][badge]5455## ✨ Features56- Fast57- Simple58- Flexible59- Modern60```6162After:63```64# TurboParse6566Parses large CSV files into typed records, streaming, without loading the whole67file into memory.6869## Install70npm install turboparse7172## Usage73... a short example that runs ...74```7576## Before you deliver7778Read the README top to bottom as a stranger. For each line ask: does this tell me79something specific and true, or is it decoration? Cut every adjective you cannot80back up, every badge a maintainer would not check, and every emoji on a heading.81What remains should let someone install and use the thing in under a minute.8283For the sentence-level fluff inside the prose, pair this with `no-filler-phrases`,84`no-em-dashes`, and `no-fancy-ascii`.
TheArmagan