ImpartLab Help — Authoring Guide
Quick start
cd docs/help/site
npm install
npm start # http://localhost:3000
How to author
- Pick the right template from
_templates/. - Fill in the front matter (id, title, roles, tiers, routes, entitlements).
- Use the tier's own vocabulary — see
glossary.csv. - Add screenshots named
<module>-<screen>-<tier>-<lang>-<yyyy-mm>.pngunderassets/screenshots/. - Open a PR; the CI coverage harness will report any nav-item gaps.
Directory map
| Path | Contents |
|---|---|
_templates/ | Starter files for each document type |
start-here/ | Pre-account path, tier overview, role chooser |
roles/ | One sub-folder per role handbook |
tiers/ | Tier guides (primary / secondary / university) |
setup/ | New-tenant onboarding path |
modules/ | Module references and how-tos |
administration/ | Users, roles, entitlements, audit log |
integrations/ | LMS, accounting, devices, SSO |
troubleshooting/ | FAQ and known issues |
release-notes/ | Per-release notes |
assets/ | Screenshots, diagrams, PDFs |
site/ | Docusaurus config |
scripts/ | Coverage harness and route-map lint |
Front matter reference
---
id: module/article-slug
title: Verb-first title
roles: [Admin, Moderator, Teacher, FormTutor, Student, Parent, Operator, Integrator]
tiers: [primary, secondary, university]
routes: [/route]
entitlements: [] # e.g. [parentPortal, aiAssistant]
pre_account: false
verified: YYYY-MM-DD
product_version: 12.x
screenshots: []
---
Style rules (summary)
- Second person, active, present tense.
- Task titles: verb first — "Record attendance", not "Attendance recording".
- Steps: numbered, one action each, UI label bold, tier noun from glossary.
- How-to ≤ 400 words; module reference ≤ 1 200 words per page.
- Alt text on every image; no colour-only meaning; headings in order (WCAG 2.2).
See style-guide.md for the full rules.