01 / 12
Lesson 01 · Software Development Fundamentals
What is a
README file?
The unsung hero of every good codebase. The first thing developers, employers, and collaborators read — and often the deciding factor in whether they keep reading.
02 / 12
The Scenario
You just downloaded
a project with 200 files.
Where do you start?
→ Pause. Discuss. Then reveal.
03 / 12
The Answer
You start here.
📁 my-project/
├── 📁 src/
├── 📁 public/
├── 📁 node_modules/
├── 📄 package.json
├── 📄 .gitignore
└── 📄 README.md ← start here
Read. Me.
The name is the instruction. It's been the universal "open this first" file since the 1970s.
Lives in the project's root directory, written in Markdown, and acts as the front door to everything else.
04 / 12
Definition
So what is it, really?
A plain-text file (usually README.md) that explains what a project is, how to use it, and why it exists.
📖
Documentation
Tells developers how the code works and how to run it.
✨
Sales Pitch
Convinces visitors the project is worth their time.
🧭
User Manual
Guides people through setup, usage, and contribution.
05 / 12
Why It Matters
First impressions are everything.
"A README is the cover letter of your codebase. If it's sloppy, no one reads the rest."
— Every senior dev, ever
For Recruiters
Often scanned before the code itself. A polished README signals professionalism.
For Collaborators
Decides whether someone contributes — or bounces in 30 seconds.
For Future You
In 6 months, you'll forget how your own project works. The README is your memory.
06 / 12
Anatomy
The 10 sections of a great README.
- Project Title — clear, descriptive name
- Description — what & why, in 1–2 sentences
- Installation — how to set it up locally
- Usage — how to actually run it, with examples
- Features — key functionality at a glance
- Tech Stack — languages, frameworks, tools
- Screenshots — visual proof it works
- Contributing — how others can help
- License — legal terms of use
- Credits / Contact — who built it
07 / 12
Markdown 101
Written in Markdown.
A simple syntax that platforms like GitHub render automatically. Easy to write, easy to read.
You write
# Heading 1
## Heading 2
**bold text**
*italic text*
- bullet point
- another point
[link](https://example.com)
`inline code`
GitHub renders
Heading 1
Heading 2
bold text
italic text
- bullet point
- another point
link inline code
08 / 12
Quality Check
Good vs. forgettable.
✗ Forgettable
- One vague line: "my project"
- No installation instructions
- No usage examples
- Outdated or broken steps
- Walls of text, no formatting
- No screenshots or demos
✓ Great
- Clear title + one-line pitch
- Copy-paste install commands
- Real usage examples
- Maintained alongside the code
- Scannable structure with headings
- Screenshots, GIFs, or live demo
09 / 12
Real Example
What it looks like in the wild.
# 🐾 PawPing
A pet GPS tracker that lets you find your dog before they find the neighbour's chickens.
## Features
- Real-time location tracking
- Geofence alerts
- Battery-efficient pings every 30 seconds
## Installation
```bash
git clone https://github.com/user/pawping.git
cd pawping
npm install
```
## Usage
```bash
npm start
```
Then visit http://localhost:3000
## Tech Stack
**Frontend:** React, Tailwind CSS
**Backend:** Node.js, Express, MongoDB
10 / 12
Your Turn
Write your own.
Pick a real or fictional project. Draft a README that hits the basics in 15 minutes.
Minimum Requirements
✓ Title
✓ One-line description
✓ Installation steps
✓ Usage example
✓ Tech stack list
✓ Screenshot placeholder
Bonus Round
- Add a status badge from shields.io
- Include a table of contents
- Add a Contributing section
- Drop in an emoji or two (don't overdo it)
11 / 12
Key Takeaways
Three things to remember.
01
It's a first impression
Treat it like a CV cover letter. Polished, clear, and confidence-inspiring.
02
Show, don't tell
Screenshots, GIFs, and live demos beat paragraphs of explanation every time.
03
Write it as you build
Not after. Documenting in real time forces clearer thinking and stops the rot.
12 / 12
Wrap-Up
Take it home.
Homework
- Add a polished README to one of your existing projects
- Find an open-source repo with a weak README → rewrite it
- Submit your file via GitHub or LMS by next class
Going Further
- Explore badges (shields.io)
- Try animated GIF demos (LICEcap, Kap)
- Look up "awesome README" on GitHub for inspiration
- Read the README of your favourite framework