Lead with the outcome
Open with what the project does in one sentence, who it is for, and the fastest path to “it works on my machine.” Commands in copy-paste blocks, not inline prose. Preview formatting in our Markdown Previewer before you push—broken tables and heading hierarchies show up instantly.
Honestly, badges are fine if they signal build status or license; a wall of shields that means nothing is noise. Pick three that answer real questions.
Open with install commands that work on a clean machine, not assumptions about global CLI tools everyone names differently.
If the project has multiple packages, say which folder to `cd` into before the first command—saves twenty minutes of silent confusion for newcomers.
Structure beats length
Install, usage, configuration, contributing, license. Skip the essay on your childhood unless it is a personal blog. Screenshots for UI projects; ASCII diagrams only when they clarify architecture, not when they show off.
Link to issues for roadmap debate; keep the README current enough that opening an issue is not the only way to learn default env vars. When you need HTML output for a static site, the Markdown to HTML converter is there—README stays Markdown.
CONTRIBUTING belongs in its own file for code style; README should stay focused on running and understanding the project quickly.
Tone for open source and internal repos
Friendly, direct, no fake corporate warmth. Say “we do not support Windows yet” instead of “platform support may vary.” List breaking changes in a CHANGELOG; README is not a release diary.
I have seen contributors bounce because prerequisites hid in paragraph four. Use a numbered list, versions pinned, and what “success” looks like after `npm test`.
Troubleshooting sections save maintainer time—collect common errors from issues quarterly instead of answering the same thread forever.
Screenshots age fast—prefer commands and short GIFs for UI-heavy setup, and date-stamp images when you cannot avoid them.
Maintenance habit
Touch the README when you touch setup scripts. Review on every major release. If an section is always wrong, delete it or fix it—stale docs are worse than none.
We preview on DroidXP because GitHub rendering surprises people with underscores and tables. Good READMEs are respect for other people’s time; that is the whole game.
Translate only if you will maintain translations; stale localized READMEs confuse more than English alone for small teams.
Link to the license file explicitly—GitHub shows it, but newcomers still ask in issues when the README buries MIT under badges.