What Makes Professional Documentation

Before You Study (5 mins)

Lesson focus: Code is read 10× more than it is written. This sentence — first attributed to Robert C. Martin, repeated by every senior engineer since — is the core of why documentation is non-optional. By Lesson 17 you've shipped real software: a containerized full-stack app with database persistence, public hosting, and AI-powered features. The architectural decisions, prompt rationale, configuration choices, and operational gotchas are all in your head right now. Today we externalize them into a real README, code comments, and architecture documentation so that the project survives contact with the most important user it will ever have: future-you, six months from now, having forgotten the details.

What you should have ready:

• Your full project from Lessons 06-17 in a GitHub repository
• Markdown fluency from Lesson 08 (JSON's cousin)
• One screenshot of your game running, or a 30-second screen recording
• About 60 minutes
• An honest answer to: "if I lost access to my own memory of this project tomorrow, what would my notes need to say?"

The Concept

Documentation has three audiences, and a good project addresses all three:

The README is the most-read file in any open-source project — and for hiring, the most-read file in any portfolio repo. A typical recruiter spends ~30 seconds on a GitHub project. The README is what they see. Get it right and you've earned the next conversation.

A professional README has six sections, in this order:

1. Title + one-line description     What is this?
2. Demo / screenshot                 Show me, don't tell me.
3. Features (3-7 bullets)            What does it do?
4. Quick start                       How do I run it?
5. Architecture (one diagram)        How is it built?
6. License + author                  Whose work is this?

The order matters. Each section answers a question the previous one created. The visitor scrolls until they're convinced or until they leave; structure the README so the most compelling 30 seconds is at the top.

Code comments are different from docs. A common beginner mistake is comments that restate the code:

// Increment i by 1
i++

// Set name to "Divyanshu"
const name = "Divyanshu"

These comments are noise. They steal attention from the reader's actual job (reading code). Useful comments explain why, not what:

// We sort by score DESC and then by createdAt ASC so that ties favor
// the earlier submission — this prevents leaderboard churn when two
// players hit the same score in quick succession.
const sorted = scores.sort((a, b) =>
  b.score - a.score || a.createdAt.localeCompare(b.createdAt)
)

The "why" comment captures the decision — the design intent that made the code take this exact shape. Six months from now, when you (or someone else) wonders "why does it sort like this?", the comment is the answer.

Architecture documentation is the third piece. For projects above ~500 lines of code, an ARCHITECTURE.md (or docs/architecture.md) becomes valuable. It captures:

• The major components and how they relate (one diagram)
• Decisions and their rationale ("we chose SQLite over Postgres because ...")
• The unsolved problems and known limitations
• The path the project is on ("if we needed to handle 10× the load, the next change would be ...")

Real teams write Architecture Decision Records (ADRs) — short numbered files (docs/adr/0001-use-sqlite.md) capturing one decision each, with context, options considered, and rationale. ADRs are durable; they survive employee turnover and become the institutional memory of a codebase.

The professional habit you're building today: the work isn't done when the code runs. The work is done when someone else can run, modify, and extend the code without your help. Documentation is the difference between "demo" and "ship."

A line worth memorizing: documentation is a love letter to your future self. Every minute spent writing it is repaid ten-fold the next time you open this codebase after a long break — or the next time someone you've never met tries to use what you built.

Quick Concepts

What We Will Build

By the end of this lesson, you will have done these specific things:

1. Wrote a real README.md with all six sections. Replaced any existing thin README. Deliberately wrote each section like you were the visitor:
   markdown

   Copy

   # Snake Game — AI-Powered Full-Stack
   
   A browser-based Snake game with a persistent online leaderboard,
   AI commentary on key events, and full-stack architecture you can
   inspect end-to-end. Built across the [ABCsteps](https://abcsteps.com)
   20-lesson AI Engineering Course.
   
   ![Snake game running](docs/screenshot.png)
   
   ## Features
   - 3D rendering via Three.js
   - Persistent online leaderboard (Express + SQLite)
   - AI commentary powered by Google Gemini Flash
   - Containerized backend with health checks
   - Public hosting via Cloudflare Tunnel
   
   ## Quick start
   ...
   

2. Added a screenshot to docs/screenshot.png and embedded it in the README. A picture establishes legitimacy in 1 second; text takes 30 seconds.
3. Wrote a Quick Start section that gets a visitor from git clone to a running app in 5 minutes:
   markdown

   Copy

   ## Quick start
   
   ```bash
   git clone [email protected]:<you>/snake-game.git
   cd snake-game
   cp .env.example .env       # then edit .env to add your GEMINI_API_KEY
   docker compose up -d
   open http://localhost:3000
   

   text

   Copy

   Tested it on a fresh checkout (e.g., from a different folder) — confirmed the steps actually work.
   
   

4. Created a .env.example file in the repo. List every env var the project reads (GEMINI_API_KEY=, PORT=, etc.) with empty values. The visitor copies it to .env and fills in their own keys. The actual .env stays in .gitignore (never commit secrets).
5. Wrote an Architecture section in the README with a single ASCII diagram:
   text

   Copy

   ┌──────────────┐    ┌──────────────────┐    ┌──────────────┐
   │   Browser    │───▶│  Express API     │───▶│   SQLite     │
   │  (Three.js)  │    │ (Lessons 12-13)  │    │ (Lesson 14)  │
   └──────────────┘    └──────────────────┘    └──────────────┘
                               │
                               ▼
                       ┌──────────────────┐
                       │  Gemini Flash    │
                       │  (Lessons 16-17) │
                       └──────────────────┘
   

6. Audited every existing code comment in your project. Removed comments that restate the code. Added comments where you remember struggling (the CORS fix, the rate-limit logic, the JSON-mode response parsing). Made sure each remaining comment answers why.
7. Added JSDoc to your three most important backend functions so future readers (and your editor's autocomplete) know the input/output shape:
   javascript

   Copy

   /**
    * Submit a new score to the leaderboard.
    * @param {string} name - Player name (1-30 chars)
    * @param {number} score - Non-negative integer
    * @returns {{id: number, name: string, score: number, createdAt: string}}
    * @throws {Error} If validation fails — caller should handle 400 response
    */
   function insertScore(name, score) { /* ... */ }
   

8. Wrote your first ADR at docs/adr/0001-use-sqlite.md:
   markdown

   Copy

   # ADR 0001: Use SQLite for the leaderboard database
   
   ## Context
   The leaderboard needs persistent storage. Options: SQLite, PostgreSQL,
   Firestore, in-memory + cloud backup.
   
   ## Decision
   SQLite via `better-sqlite3`, in WAL mode, mounted as a Docker volume.
   
   ## Rationale
   - Single-file simplicity matches solo-developer ops
   - Read performance is excellent for leaderboard queries (<10K rows)
   - WAL mode handles the few concurrent writes we expect
   - No separate server to deploy or pay for
   
   ## Consequences
   - When usage exceeds ~100 concurrent writes, we'd migrate to PostgreSQL
   - Backup strategy is "copy the .db file" — simple but manual
   

9. Pushed everything to GitHub. Visited your repo's GitHub page. Read the README from the top as if you were a stranger. Made one more pass of edits.

The final test of step 9 is the goal. The README a stranger reads in 30 seconds is the README that earns you the next conversation.

Think About

Before studying, consider:

1. Find a popular open-source project on GitHub (e.g., tailwindcss or supabase). Read their README. Notice the structure, the tone, the screenshots, the "how to install in 30 seconds" sections. What patterns do they all share? (Compelling first 30 seconds, demo first, install second, features third, contribution last.)
2. If your worst day's bug — production-down at 11pm — happened to your Snake game six months from now, what would you wish your future-self had documented? (Probably: how to redeploy, where the secrets live, what dependencies are critical, who else needs to be told. The runbook is documentation too.)

By the End

After this lesson, you'll:

• ✅ Have a polished README.md covering all six sections (title, demo, features, quick start, architecture, license)
• ✅ Have a screenshot or short recording embedded in the README
• ✅ Have a .env.example listing every secret the project needs
• ✅ Have removed comments that restate the code; kept ones that explain decisions
• ✅ Have JSDoc on at least 3 important backend functions
• ✅ Have your first Architecture Decision Record at docs/adr/0001-use-sqlite.md
• ✅ Be able to hand the GitHub URL to anyone and have them get the project running in 5 minutes

Code is read 10× more than it is written. Documentation is the love letter to that majority. ✨

What We Learned

• Documentation has three audiences: the first-time visitor (answered by the README), the contributor (answered by code comments + architecture docs), the future-you (answered by all of the above + a NOTES.md if needed).
• The README is the most-read file in any project. Six sections in order: title, demo, features, quick start, architecture, license. A typical recruiter spends ~30 seconds on a portfolio repo — the README is the entire conversation.
• Comments explain why, not what. i++ // increment i is noise. // Sort ties by createdAt ASC so leaderboard doesn't churn is signal. The decision is what's worth preserving.
• JSDoc on important functions gives both readers and editors the input/output contract. Free autocomplete for everyone who imports the function.
• ADRs (Architecture Decision Records) are short numbered files that capture one significant decision each — context, options considered, rationale. They become the institutional memory that survives employee turnover.
• .env.example is the doctrine for secrets: list every env var the project needs, with empty values, in source control. The actual .env stays in .gitignore forever.
• Test the docs. Pretend you're a stranger who just landed on your repo. Can you go from git clone to "running" in five minutes? If not, the docs need work.

Commands We Used

# Take a screenshot for the README
# macOS: Cmd+Shift+4 → select region → saved to Desktop, move to docs/
# Linux: gnome-screenshot or scrot
# Windows: Win+Shift+S → snipping tool

# Capture a quick screen recording (10-30 seconds)
# macOS: Cmd+Shift+5 → record selected portion
# Linux: peek or kazam
# Windows: Win+G → Game Bar

# Convert .mov to .gif for embedding in README (smaller file)
ffmpeg -i recording.mov -vf "fps=15,scale=720:-1:flags=lanczos" docs/demo.gif

# Once the README is in place, sanity-test it from a stranger's perspective:
# Clone the repo to /tmp and follow your own Quick Start
cd /tmp
git clone [email protected]:<you>/snake-game.git fresh-clone
cd fresh-clone
cp .env.example .env  # then edit
docker compose up -d
open http://localhost:3000

# If any step fails, your README needs updating.

A complete README template you can adapt:

# Snake Game — AI-Powered Full-Stack

A browser-based Snake game with a persistent online leaderboard, AI
commentary on key events, and a full-stack architecture you can
inspect end-to-end. Built across the [ABCsteps](https://abcsteps.com)
20-lesson AI Engineering Course.

![Demo](docs/demo.gif)

## Features
- 3D rendering with Three.js (Lesson 03)
- Containerized backend with Docker (Lesson 06)
- Public hosting via Cloudflare Tunnel (Lesson 07)
- Persistent online leaderboard — Express + SQLite (Lessons 13-14)
- AI commentary powered by Google Gemini Flash (Lessons 16-17)

## Quick start

```bash
git clone [email protected]:<your-username>/snake-game.git
cd snake-game
cp .env.example .env       # then edit .env to add your GEMINI_API_KEY
docker compose up -d
open http://localhost:3000
```

Need a Gemini API key? Get one free at [aistudio.google.com/apikey](https://aistudio.google.com/apikey).

## Architecture

```
┌──────────────┐    ┌──────────────────┐    ┌──────────────┐
│   Browser    │───▶│   Express API    │───▶│   SQLite     │
│  (Three.js)  │    │  (Node.js + cors)│    │ (better-sqlite3)│
└──────────────┘    └────────┬─────────┘    └──────────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │  Gemini Flash    │
                    │   (commentary)   │
                    └──────────────────┘
```

See [`docs/adr/`](docs/adr/) for architecture decisions.

## Local development

```bash
# Frontend
cd frontend && npm install && npm run dev   # → http://localhost:3000

# Backend
cd backend && npm install && npm run dev    # → http://localhost:3001

# Database — created automatically on first backend run
ls backend/data/scores.db
```

## License

MIT — see [LICENSE](LICENSE). Built by [@your-username](https://github.com/your-username) as a learner project.

A clean .env.example:

# Gemini API key — get one free at https://aistudio.google.com/apikey
GEMINI_API_KEY=

# Backend port (defaults to 3001 if unset)
PORT=

# Frontend origin allowed by CORS (comma-separated for multiple)
ALLOWED_ORIGINS=http://localhost:3000

A first ADR — docs/adr/0001-use-sqlite.md:

# ADR 0001: Use SQLite for the leaderboard database

Status: Accepted · Date: 2026-04-29

## Context
The leaderboard needs persistent storage that survives container restart.
The project is solo-developed at small scale; we expect <100 concurrent
users in the foreseeable future.

## Decision
Use SQLite via `better-sqlite3`, in WAL journal mode, mounted as a Docker
volume so the file lives on the host filesystem and survives container
restart.

## Alternatives considered
- **PostgreSQL**: separate server process, more capable for heavy concurrent
  writes, but operational overhead is non-trivial for single-developer scale.
- **Firestore / DynamoDB**: managed but adds vendor lock-in and a network
  hop for every query.
- **In-memory with periodic backup**: simpler but loses recent data on crash.

## Rationale
- Single-file simplicity matches the operational maturity of a solo project.
- Read performance is excellent at the expected scale (<10K rows).
- WAL mode handles the few concurrent writes we expect.
- Migration to PostgreSQL is straightforward when we need it (same SQL).

## Consequences
- We don't get connection pooling, replication, or multi-writer scenarios.
- Backups are manual ("copy the .db file") — acceptable today; a problem
  if we need point-in-time recovery.
- The migration path to PostgreSQL exists if we exceed SQLite's limits.

Why It Matters

Documentation is the discipline that distinguishes engineers who finish things from engineers who start things. Both categories ship code. Only the first category ships work that survives them — that other people can pick up, that future-self can revisit, that becomes a foundation rather than a one-time effort.

The professional reality: at most companies, code with documentation gets reviewed, gets shipped, gets credited. Code without documentation gets blocked at code review or quietly abandoned six months later when no one remembers why it exists. The asymmetry compounds. Engineers known for thorough documentation get pulled into more interesting work because their existing work is durable.

For a portfolio repo specifically, the README is the single most important asset in your job-search arsenal in 2026. Hiring managers don't read code first; they read READMEs. They form an opinion in 30 seconds about whether the engineer can communicate. Most repos fail this test. Yours, after this lesson, won't.

What this lesson glossed over but you'll meet:

• Generated docs from code — TypeDoc, JSDoc-to-HTML pipelines, Sphinx for Python. For libraries with public APIs, you generate docs from the JSDoc comments themselves.
• Tutorial-style docs — separate from reference docs. The "how to do X" content is different from "here are all the functions and their signatures."
• Diátaxis framework — a popular taxonomy splitting docs into Tutorials / How-To Guides / Reference / Explanation. Worth reading once.
• Code-as-docs — runnable examples in your README, doctests, executable Markdown (mdbook, mdsh). Ensures docs don't drift from reality.
• Changelog discipline — CHANGELOG.md updated with every release. Keep-a-Changelog format is the dominant convention.

For the broader practice of writing things future-you will read, What is JSON and Why Does Every Application Use It is a side-companion — the discipline of self-documenting data structures parallels the discipline of self-documenting code.

Checklist

• My README has a title, one-line description, demo (image or gif), features, quick start, architecture, license
• My demo (screenshot or gif) is embedded near the top
• My quick start works on a fresh clone — I tested it
• I have a .env.example listing every secret the project needs
• I removed comments that restate the code; kept ones that explain decisions
• I added JSDoc to at least 3 important backend functions
• I wrote my first ADR documenting one significant architectural decision
• A friend / classmate / family member could clone my repo and run it without asking me a question

Quick Quiz

Q1: What is the first file someone looks at on a GitHub project?

• A) package.json
• B) README.md ✓
• C) index.js

Q2: What makes a comment "bad"?

• A) It's too short
• B) It restates what the code does (i++ // increment i) instead of explaining why ✓
• C) It's longer than the code it comments

Q3: Why include a screenshot in the README?

• A) GitHub requires it
• B) A picture establishes legitimacy and conveys what-this-does in 1 second instead of 30 ✓
• C) It pads the file size

Q4: What goes in .env.example?

• A) Real API keys (so contributors can use them)
• B) The list of every env var the project reads, with empty values — never real secrets ✓
• C) The output of printenv

Q5: What is an Architecture Decision Record (ADR)?

• A) A short numbered file capturing one design decision with context and rationale ✓
• B) A required GitHub feature
• C) A type of pull request

Bonus Challenge

Make a 30-second screen recording of your game running and your leaderboard updating across two browser tabs. Convert it to a GIF (using ffmpeg or ezgif.com). Embed it as the demo in your README. The first time someone scrolls to your repo and sees a working game animating in front of them, before reading a single line, your project earns a level of credibility text alone cannot match. This single artefact is one of the highest-leverage things you can produce in the entire course.

Next Lesson

Lesson 19: Final Polish and Verification

You'll learn: Tomorrow we close the build phase. The verification ritual you practiced in the milestones (Lessons 10 and 15) gets applied one more time, with the final-polish discipline that takes a "working" project to a "shipped" one — defensive UX, performance audits, the honest pass over edges.

Documentation is the love letter to your future self. ✨