README files

README files are the welcome sign for the project and form the first impression of the project for new users and potential contributors. An effective README file tells your audience what your project does, how to use it, and how they can help out.

The README content keeps important information close to the code and signals that a community is active. A quality README elevates the quality of any project and shares information that makes the project more attractive to contributors.

As the central hub for all the information that users need to understand a project, ensure your README includes all of the essential content.

Essential content

1. Title
2. High-level overview
   • A few short statements describing why your project exists and what it does
3. Installation and dependencies
4. Getting started usage instructions
5. How users can get help
6. Links to essential information
   • Documentation
   • Use absolute links so that the links work on npm
   • Where to go to find more details
   • Contributor guidelines
   • Project license

Nice to haves

• Table of contents
• Tech stack and features
• A link to a working instance
• A screenshot of the project's user interface
• GIFs
• Code samples
• Link to contributing guidelines
• Link to code of conduct
• Badges
• Tests
• Code examples and how to run them

Need inspiration? See How to Write a Great README.

zkApp tutorial examples

Each zkApp tutorial that includes example code must have a README that fulfills the basic README requirements.

For accuracy, after a tutorial is verified, be sure to update the verified information with the o1js release and the verified date.