Short answer
“READMEs do more than explain how to use your project. They also explain why your project matters, and what your users can do with it.” - Open Source Guides
Detailed explanation
Get started from an example!
The README answers the following questions:
- What does the Asset do?
- Why is the Asset useful?
- How do I get started?
- Where can I get more help, if I need it?
The README is the file where you can share some additional information about your Asset, for example:
- The contributions Asset handling
- Goals of the Asset
- Some information about licenses and attribution
- If you don’t want to accept contributions
- If your Asset is not yet ready for production
Common pitfalls
- Outdated content: buggy install commands, deprecated APIs, old screenshots. Worse than no README because it actively misleads. Pin examples to real tests or run them after every major change.
- “Obvious to me” assumptions: make install with no mention of dependencies, build tools, or supported platforms. What’s clear after six months of development is opaque to a first-time visitor.
- The “see the docs” README: a single link to a wiki that’s empty, disorganized, or behind auth. The README is the entry point.