After this lesson, you will be able to: Write a README that actually helps, document the why with inline comments, and generate reference docs from code with JSDoc/TSDoc and OpenAPI.
Documentation is an engineering deliverable, not an afterthought. The README is the first thing a teammate, a hiring manager, or future-you reads. Good docs are the difference between code that other people can use and code only you can run. This lesson covers the three layers: project docs (README), inline docs (the why), and reference docs (generated from code).
Project docs answer 'what is this and how do I run it' (the README, a docs/ folder). Inline docs answer 'why is this code doing something non-obvious' (comments at the point of confusion). Reference docs answer 'what does this function/endpoint take and return' (generated from JSDoc/TSDoc or an OpenAPI spec). Each layer has a different reader and a different job. The mistake is writing none of them, or writing the wrong one (a wall of WHAT comments instead of a README).
Order matters. A reader decides whether to keep going in the first ten seconds.
One-line description: what this project is, in a sentence.
A screenshot or demo GIF if there is any UI, or a short usage example if it is a library/CLI.
Quickstart: the exact commands to install and run locally (clone, install, copy .env.example, run). Test them on a clean checkout.
Configuration: what environment variables exist and what each does.
Project structure: a few lines on where the important code lives (helps the reading-code skill from the last lesson).
Contributing + license if it is open source.
Skip vanity badges no one maintains and 'about me' essays. Brevity wins.
Structured comments power editor tooltips AND generate an API reference site with TypeDoc.
/*** Charges a customer and records the payment.** @param customerId - Stripe customer ID (starts with `cus_`).* @param amountCents - Amount to charge, in the smallest currency unit.* @returns The created payment record.* @throws {PaymentError} If the card is declined or the customer is missing.** @example* const payment = await charge("cus_123", 1500); // $15.00*/export async function charge(customerId: string, amountCents: number): Promise<Payment> {// ...}// Editors show this on hover. TypeDoc turns it into a docs site.// You write it once, in the same file as the code, so it stays in sync.
This is the same rule from the code-quality lesson, applied to documentation. A comment that restates the code (`// loop over users`) is noise that goes stale. A comment that explains a decision (`// We retry only on 5xx; 4xx means the request itself is wrong`) is gold, because the reasoning is invisible from the code alone. If you are writing many WHAT comments, fix the names instead. Reserve comments for the surprising, the regulatory, and the 'do not change this without reading PR #482'.
A README that lists features but never says how to run the thing. Quickstart first. Docs that drift from the code because they live in a separate wiki nobody updates. Keep reference docs in the code (JSDoc) so they move with it. Documenting private internals as if they were a public API. Document the surface other people use. No .env.example, so a new contributor cannot start the project. Writing docs once and never again. Update the README in the same PR that changes behavior, the way you update tests.
Pick the option most likely to stay accurate.
Sign in and purchase access to unlock this lesson.