Docs and READMEs

Who wrote this, and why?

Six months after building the Garden Defense shop, Kai opens shop.js and finds this:

price = price * 0.85; // change price

Why 0.85? A sale? A bug? Kai wrote it and can't remember. Meanwhile, you just cloned the repo (downloaded your own copy) and can't even find how to start the game.

Documentation, or docs, is the writing that explains a project: how to run it, how it's organised, and why it was built this way. Code tells the computer what to do. Docs tell people, and AI agents, why.

Who reads the docs?

• Future youIn six months you will remember the game, not the details. Docs are notes from you to you.
• TeammatesA new teammate should get the game running on day one without asking five questions.
• AI agentsClaude Code reads the repo before it changes anything, so clear docs mean fewer wrong guesses. Its own notes file, CLAUDE.md, is covered in the Claude helpers lesson.
• ReviewersA pull request that updates the docs tells reviewers what the change is meant to do.

Bolt says: A CLAUDE.md can point to the README by writing @README, so Claude Code loads it at the start of each session. The facts stay in one file instead of two.

The README: the front door

A README is the first file to read in a project, usually README.md at the top of the repo. GitHub shows it on the repo's front page automatically. Ours answers five questions:

• What it isOne or two sentences: "Hyper Shards, a space shooter PWA built with PixiJS."
• How to run itThe exact commands: npm install, then npm run dev.
• How to test itnpm test for the unit tests, npx playwright test for the robot players.
• How to deploy itHow a new version reaches players, and who is allowed to do it.
• Where things liveA short map: src/ for game code, balance.json for the numbers, tests/ for the tests.

Markdown in two minutes

README.md ends in .md because it's written in Markdown: plain text with a few symbols that turn into formatting. John Gruber created it in 2004, and GitHub, Discord and Claude all use it.

• # Title is a big heading, ## Run it a smaller one.
• - item makes a bullet list.
• **bold** makes bold text, and backticks mark `code`.
• [deploy guide](docs/deploy.md) makes a link.
• A line of three backticks starts and ends a code block.

GitHub shows the formatting. The editor shows the symbols, and it still reads well.

Comments say why, not what

A comment is a note in the code that the computer skips, after // in JavaScript. Kai's // change price only repeats what the code already says. A good comment explains what the code can't: the reason, the trade-off, the warning.

// Weekend sale: 15% off seeds, agreed in #48.
// Remove when the sale ends.

When a comment only explains what, try a better name instead. calc2() needs a comment. applyWeekendSale() doesn't.

Docs live next to the code

Docs on a forgotten website, or only in someone's head, go out of date. So we keep them in the repo: the README at the top, longer guides in a docs/ folder, all in Markdown.

Then docs change in the same pull request as the code. Renaming npm run dev to npm start? Update the README in that PR, and the reviewer checks it. A README with the wrong command can waste more time than no README at all.

Write each fact in one place, and link to it from everywhere else. Two copies of a fact drift apart.

A changelog for every version

A CHANGELOG.md lists the notable changes in each version, newest first. A popular convention, Keep a Changelog, sorts them under headings like Added, Changed, Fixed and Security, with an Unreleased section at the top that fills up as pull requests merge.

## [1.2.0] - 2026-10-09
### Fixed
- The ship can shoot again after the pause menu.

It is written for people, not machines. Turning it into patch notes for players is a Stage 9 lesson: Version numbers and patch notes.

Bolt says: Docs say what the code should do. Next lesson: tests, small programs that check it really does.