Readme Best Practices

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".