For a change note, readers need to distinguish what changed from what they must still check. A short section and an unchecked task are easier to interpret than an uninterrupted paragraph with a command buried inside it.
Start with an original change note
Copy this illustrative Markdown into a draft .md file. Replace the sample text and paths with your repository's actual details:
# Equipment booking update
The booking form now asks for a return date.
## Review before release
- [x] Explain the new field
- [ ] Confirm the reminder wording
Read the [booking instructions](docs/booking.md).
```text
Return date: YYYY-MM-DD
```
In a rendered file, the title should become a heading, the two review items should have different checkbox states, and the date placeholder should remain literal code. The docs/booking.md target is a fixture path. It must exist relative to the real file before that link is useful.
Keep descriptive words inside the brackets. “Booking instructions” tells readers what opens; a bare “here” becomes unclear when someone copies the sentence elsewhere.
Give code its own boundaries
Use single backticks around a short field name such as return_date. Use a fenced block for a multi-line example or command. Put the opening and closing fences on separate lines, with the example between them.
If every following section appears as code, look for an unclosed fence before changing the wording. If your explanation needs to display three backticks, surround that explanation with a longer fence, as in the four-backtick example above.
Keep a table for information that needs columns
A review note can use a table when each row has the same relationship:
| Field | Required check |
| --- | --- |
| Return date | Confirm the date format |
| Contact email | Confirm the reply address |
Leave a blank line before the table. A literal pipe inside a cell needs escaping as \|, or it can split the cell. Columns need not line up perfectly in the raw file. GitHub table syntax
A long explanation usually reads better as paragraphs. On a phone, a wide table can make the relationship harder to follow even when the syntax is correct.
Check the actual destination
GitHub Flavored Markdown extends CommonMark with features including tables and task lists. GitHub also performs processing and sanitization beyond parsing the syntax, so embedded raw HTML is not a route to an arbitrary interactive web page. GitHub Flavored Markdown specification
Preview the note where it will live. Open its links, confirm headings form a sensible outline, and check that the unfinished task is still unchecked. For repository files, confirm relative paths from that file's location. For an issue or pull request, review the final rendered comment rather than assuming a local Markdown preview is identical.
For the larger job of documenting setup and first-run behavior, use the GitHub README template. A change note can remain much smaller: explain this change, preserve its exact example, and leave the outstanding review visible.