Docs site QA checklist (maintainers)
Audience
For maintainers verifying the user docs experience. End users should start at Start here.
A. Machine checks
cd website && yarn build
cd website && yarn serve
# default http://localhost:3000/
Confirm:
- Navbar Docs opens Start here (
/docs/guide/intro) - Sidebar Contribute & engineering is collapsed by default
- Search hits guide titles (DBML, reverse, self-host); blog is indexed
- Footer has Demo / Docs / GitHub (not copyright-only)
- Locale dropdown switches Simplified Chinese (zh-Hans) / English; under EN, guides and deployment / data-format / security-model / contrib docs / ADRs are English (not Chinese fallback)
- Production build loads Baidu Tongji (
hm.baidu.com); SPA navigations still track
B. User journey (~15 minutes)
| # | Task | Pass criteria |
|---|---|---|
| 1 | In 30s know what to click next | intro / what-is; no ADR required |
| 2 | Follow “save version & diff” via Demo | Mentions read-only Demo → Copy to my project; diff works |
| 3 | Read “Import DBML” | Success state + ≥2 troubleshooting rows |
| 4 | Read “Five-minute self-host” | Copy-pasteable commands; link to full deployment |
| 5 | Find compare | Sidebar or intro → /compare |
| 6 | Accidentally open roadmap / vision | Top callout sends you back to guides |
C. Polish bar
- Guide first screens use user language only (no “verification points / UTM / north-star”)
- From intro, ≤3 clicks to try / migrate / self-host
- A stranger screenshot reads as a product manual, not an internal wiki