README Code Sections

A one-sentence description and prerequisites — every code block in a README should be introduced by a prose sentence that tells the reader: what this command does, and what they need before running it.

Good README code block pattern:

## Installation

Requires Node.js ≥ 18. Install the package with:

```bash
npm install my-package
```

What the prose line should answer:
• What the command does ("Installs the package and its dependencies")
• Prerequisites ("Requires Node.js ≥ 18", "Run as root", "Must be in the project directory")
• Expected outcome for long commands ("This may take 1–2 minutes on first run")

Language tag on the code fence (bash, js, python, yaml) enables syntax highlighting in GitHub and documentation tools — also important, but the question is about the missing surrounding prose.

Option B — better Quick Start section. Differences:

1. Introductory sentence: tells the reader what the commands collectively achieve ("clone, install, start")
2. Language tag: bash enables syntax highlighting
3. One command per line: easier to run step by step, easier to spot errors
4. Post-command context: "The dev server runs at http://localhost:3000" — tells the reader what success looks like

Option A problems:
• No prose intro — reader must infer what each command does
• No language tag (no syntax highlighting)
• Commands chained with && on one line — if one fails, hard to see where
• No indication of what success looks like

Quick Start writing principles:
• One clear action per step
• Say what the reader should see when it works ("You should see: Server running")
• Include the minimal number of commands to go from zero to working

Inline comments + brief intro sentence — the most effective approach for annotated READMEs.

Example of a well-annotated config block:

Create `.env` in the project root. Required fields:

```env
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
JWT_SECRET=your-secret-here          # min 32 characters
REDIS_URL=redis://localhost:6379      # optional; used for session caching
MAX_WORKERS=4                        # set to CPU core count
```

Good in-block comment patterns:
• # min 32 characters — constraint not visible from the key name
• # optional; used for session caching — indicates what happens if omitted
• # set to CPU core count — recommendation, not a hard rule

What NOT to do:
• All-text wall before the block — loses readers before they see the code
• Footnotes — require readers to scroll back and forth
• No annotation — readers won't know which fields are optional, what format to use, or what constraints apply

Table or inline comments — two common patterns in real-world READMEs:

Markdown table approach:

| Variable | Required | Default | Description |
|---|---|---|---|
| DATABASE_URL | Yes | — | PostgreSQL connection string |
| REDIS_URL | No | None | Redis for caching (optional) |
| PORT | No | 3000 | Server listen port |

Inline comment approach:

```env
DATABASE_URL=postgres://...     # required
REDIS_URL=redis://...           # optional, default: disabled
PORT=3000                       # optional, default: 3000
```

Choose based on project complexity:
• 2–4 variables → inline comments are enough
• 5+ variables with types, defaults, examples → Markdown table is clearer
• Public API documentation → table (users expect structured reference docs)

Always include: required/optional, the default value for optional variables, and what happens if an optional variable is missing.

The expected response — request-only examples leave developers guessing whether their request worked.

Good HTTP example pattern:

Authenticate and retrieve a user:

```http
GET /api/v1/users/usr_123
Authorization: Bearer <token>
```

**Response (200 OK):**
```json
{
  "id": "usr_123",
  "email": "alex@example.com",
  "role": "admin"
}
```

**Error (404):**
```json
{
  "error": "user_not_found",
  "message": "No user with ID usr_123"
}
```

What to always show alongside a request:
• Success response — status code + body
• Error response — at least one common error case
• Headers required — Authorization format, Content-Type if relevant
• Path parameter meaning — "usr_123" → explain the ID format if non-obvious

Option C — descriptive link text with a clear URL.

Link writing rules for README and technical documentation:

❌ Bad link text:
• "See the docs." — what docs? Which part?
• "Click here" — no information about the destination
• "here", "this", "link" — meaningless out of context

✓ Good link text pattern:
• Describe what the reader will find: "Full API reference, examples, and troubleshooting"
• Include the visible URL for printed/copy-pasted contexts
• Be specific about the destination: "JSDoc for the fetch() options object" not "documentation"

Why this matters in READMEs:
• GitHub renders Markdown — links are clickable but the text is what readers scan
• Screen readers announce link text, not URLs
• When a developer copies a README to a wiki or issue, bare "click here" becomes meaningless
• Specific link text helps readers decide whether to follow the link before clicking