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 enforces README best practices that prioritize immediate clarity and user engagement over comprehensive documentation. It guides you to lead with a compelling one-liner, embed working code examples early, use scannable tables instead of bullet lists, and maintain a conversational tone that avoids marketing clichés.
- Start with a bold one-liner value proposition instead of generic "A tool that..." descriptions
- Include working code examples in the first 5 lines to demonstrate immediate value
- Replace feature bullet lists with two-column tables for faster scanning
- Ensure Quick Start sections are copy-paste ready with zero setup friction
- Vary sentence structure and length to maintain reader engagement
- Strip marketing jargon (seamless, robust, comprehensive, cutting-edge) from descriptions
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
ROS and ROS2 best practices for packages, nodes, interfaces, timing, and testing.
Build RTL-ready apps with logical CSS, Tailwind utilities, and automated auditing.
Rust best practices for Solana smart contract development using Anchor framework and Solana SDK
General Rust rules for safe, idiomatic application and library development
Senior Salesforce Apex development guide with design patterns, testability, and best practices.
Scala and Kafka development practices with clean code, functional patterns, and testing guidelines.