Appearance
Module doc template
This page is the authoring convention for Retailer OS docs. Copy it into site/modules/<module>/ and fill it in so every module reads the same way. It follows the Diátaxis split: an overview that explains, feature pages that show you how, a reference for lookup, and an FAQ.
Files per module
Store each module under site/modules/<module>/:
| File | Purpose |
|---|---|
index.md | Overview — what the module is for, who uses it, and the map of its screens. |
<feature>.md | How-to — one page per major feature, written as numbered steps. |
reference.md | Reference — tables: fields, statuses, permissions, keyboard shortcuts. |
faq.md | FAQ — the questions support actually gets, answered plainly. |
Conventions
- Headings are sentence case. Use
##and###only (the right-hand outline shows levels 2–3). - Bold the exact UI label a user clicks — Add item, Setup → Payments, the Live badge.
- Numbered steps for anything procedural. One action per step.
- Callouts for asides:
TIP
Short, helpful shortcuts go in a tip.
WARNING
Irreversible or billing-affecting actions go in a warning.
NOTE
Context that isn't a step goes in a note.
- Screenshots live under
site/public/img/<module>/and are referenced as. They're captured from the seeded demo store so the numbers reconcile across pages. Every image is click-to-zoom. - Never invent features or fields. If it isn't in the product, it isn't in the docs.
- Link related pages with relative links so readers can move sideways.
Screenshot naming
Prefix each file with a short module code so images sort together, e.g. pos-sale.png, pos-returns.png, inv-items.png. Capture at a consistent width on the seeded demo tenant (Northwind Retail), signed in as an owner, with a location selected.