A GitHub repository without a proper README is like a restaurant with no menu. Sure, people can wander in and look around the kitchen, but most of them will just leave. Your README is the single most important file in your repository. It is the first thing people see, the first thing they judge, and often the only thing they read before deciding whether your project is worth their time.
"Your repo has 47 files and zero documentation. What is this, an escape room? -- Sally"
Why Your README Matters More Than You Think
Whether you are building an open source library, showcasing a personal project for job applications, or sharing an internal tool with your team, the README is your project's first impression. Recruiters look at it. Potential contributors look at it. Future-you, six months from now, trying to remember how this thing works, will look at it. A great README is not about being verbose. It is about being clear, organized, and respectful of the reader's time.
The Essential Sections
1. Project Title and Description
Start with a clear, descriptive title and a one to three sentence summary of what the project does. Not what technologies it uses. Not what inspired it. What it does. "A CLI tool that converts CSV files to typed TypeScript interfaces" is clear. "A project built with Node.js and TypeScript" is not.
2. Quick Visual (Screenshot, GIF, or Demo Link)
A picture is worth a thousand lines of documentation. If your project has a UI, include a screenshot or a short GIF showing it in action. If it is a CLI tool, show terminal output. If it is an API, show a sample request and response. This gives visitors an instant understanding of what they are looking at.
3. Installation
Provide exact, copy-pasteable commands to get the project running. Do not assume the reader knows your package manager, your environment, or your operating system. Include prerequisites (Node version, Python version, system dependencies). If there are environment variables, list them. If there is a setup script, reference it. The goal is that someone can go from zero to running in under five minutes.
4. Usage Examples
Show the two or three most common use cases with actual code examples. Not pseudo-code, not descriptions of what the code would look like. Real, runnable code that someone can copy, paste, and execute. If your project has an API, show the most common endpoints. If it is a library, show the primary functions. If it is a tool, show the main commands.
5. Tech Stack and Architecture (Optional but Impressive)
For portfolio projects especially, include a brief tech stack section. This helps recruiters and other developers quickly understand your technical choices. Even better: explain why you chose certain technologies. "Used Redis for session storage because the app needs sub-millisecond reads at scale" shows decision-making ability.
6. Contributing Guidelines
If you want contributions, tell people how to contribute. Link to a CONTRIBUTING.md if you have one, or at minimum explain how to set up the development environment, run tests, and submit a pull request. If you do not want contributions, say so politely. Either way, be explicit.
7. License
Include a license. No license means no one can legally use your code. MIT and Apache 2.0 are the most common for open source. Pick one and include a LICENSE file. Mention it in the README.
The Complete Checklist
Run through this for every repository:
- Clear project title that describes what it does
- One to three sentence description of the project's purpose
- Screenshot, GIF, or demo link
- Badges (build status, version, license) if applicable
- Installation instructions with exact commands
- Prerequisites and environment setup
- Usage examples with real, runnable code
- API documentation or link to docs (if applicable)
- Tech stack with brief rationale for choices
- Contributing guidelines or a note about contributions
- License file and mention in README
- Contact info or link to issues for questions
Bad README vs Good README
Bad: "This is a todo app built with React. Run npm start to start it." This tells you nothing about what makes it different, how to set it up properly, or whether it even works.
Good: "A full-stack todo application with real-time sync, offline support, and collaborative editing. Built with React, Express, and Socket.io. Supports multiple users with conflict resolution. [Screenshot] [Demo Link]. Prerequisites: Node 18+, Redis 7+. Setup: git clone, npm install, cp .env.example .env, npm run dev." In thirty seconds, you know exactly what this project is, what makes it interesting, and how to get it running.
"Your README says 'TODO: add documentation.' That TODO is older than some of your dependencies. -- Sally"
How Sally Reviews GitHub READMEs
When you submit a GitHub repo URL to Cynical Sally, the README is front and center. Sally checks for completeness, clarity, installation instructions, usage examples, and whether the README actually helps someone understand and use the project. Level 1 delivers a punchy roast of the most obvious gaps. Level 2 gives a detailed scorecard covering documentation quality, structure, developer experience, and specific improvements with evidence for every point.
Your README is the landing page of your code. If it does not sell the project in the first ten seconds, everything else you built is invisible. Treat it like the most important page of your portfolio, because for many recruiters and developers, it is.