readme best practices
via PatrickJS/awesome-cursorrules
Write READMEs that convert readers in 3-5 seconds with landing-page structure and working code examples.
What is readme best practices?
This rule applies best practices for README documentation, treating them as landing pages rather than API docs. It emphasizes immediate value communication through punchy one-liners, working code examples in the first 5 lines, and scannable formatting that respects the reader's decision window.
- Start with a bold one-liner value proposition instead of generic tool descriptions
- Include working code examples in the first 5 lines to demonstrate immediate value
- Use feature tables instead of bullet lists for faster scanning
- Write Quick Start sections that are copy-paste ready with zero-to-running in 30 seconds
- Vary sentence lengths and structure to avoid monotonous formatting
- Avoid marketing buzzwords like 'seamless', 'robust', 'comprehensive', and 'cutting-edge'
Applies to
File patterns this rule matches.
Rule definition (reference)
Source of truth, from the repository.
Write READMEs like landing pages, not API docs. The reader decides in 3-5 seconds.
Start with a bold one-liner saying what it does and why someone should care. Not "A tool that..." - a punchline. Put a working code example in the first 5 lines. Show the value prop immediately. Use feature tables (two columns) instead of Feature: bullet lists. Tables scan faster. Quick Start must be copy-paste ready. No $ prefix on bash commands. Zero to running in 30 seconds. Vary sentence lengths and structure. Mix one-liners with short paragraphs and tables. Not walls of same-length bullets. Never use "seamless", "robust", "comprehensive", "cutting-edge", or other AI marketing words. Never open with "In today's..." or close with "Happy coding!" Check that referenced assets (demo.gif, screenshots) actually exist on disk before adding image links. Author section should include a visual card or badge, not just plain text "Made by username".
Related rules
Senior full-stack TypeScript, React, Node.js guidance with clean architecture, testing, and WHY-oriented reasoning.
Quantitative factor research skills for designing, evaluating, and mining alpha factors in equities markets.
Android development with Jetpack Compose, clean architecture, and Material Design 3.
Angular development with Novo Elements UI library using standalone components.
Expert Angular 18 + TypeScript development with Jest, emphasizing clean code and performance.
Manage Kubernetes clusters, add-ons, stacks, and credentials via the Ankra CLI platform.