Lesson 4
README and Issue Templates
Draft README files, changelogs, and issue templates with clear structure and reusable sections.
Markdown is most valuable when it follows predictable document shapes.
README structure
A practical open-source README often includes:
# Project name
One-line summary.
## Features
- Feature A
- Feature B
## Quick start
```bash
npm install
npm run dev
Configuration
Explain env vars or config files.
License
MIT
Readers scan README files quickly. Put the project purpose and quick start near the top.
## CHANGELOG patterns
```markdown
## 1.2.0 - 2026-05-31
### Added
- CSV to JSON converter
### Fixed
- toolbar wrap on mobile
Use dated sections and grouped change types so release notes stay scannable.
Issue templates
Issue templates should ask for reproducible information:
## Bug report
**Describe the bug**
**Steps to reproduce**
1.
2.
**Expected behavior**
**Environment**
- OS:
- Browser:
Templates reduce back-and-forth by making missing details obvious.
Key takeaway
Strong README and issue Markdown is structural, not decorative. Use headings to create scan paths, and keep examples close to the sections that need them.
Load the README or issue examples in the Markdown Preview / Markdown to HTML tool to check heading hierarchy before publishing.