Skip to content

Writing these docs

For the ChouyLok team. Customers don't need this page.

Who you are writing for

A shop owner or cashier, on a phone, with a customer waiting. Not a developer.

  • Write what the reader should do, in order, one action per step.
  • Use the words on screen. If the button says Charge, write "tap Charge", not "initiate the payment flow".
  • Say what happens after each step, so the reader knows they got it right.
  • If something can't be undone, say so before the step, in a !!! warning.

The technical docs in chouylok_docs/ are the source of truth for how it works — read them while writing, but don't copy their voice, and never link customers to them.

Never copy from the backend documentation

Some of the internal docs describe infrastructure, deployment and known weaknesses. This site is public — nothing from those files belongs here, not even paraphrased.

Editing

.venv/bin/mkdocs serve      # http://127.0.0.1:8010, reloads as you save
                            # 8000 is the Laravel container; dev_addr in mkdocs.yml pins 8010

Add a page: create the .md file, then add one line to nav: in mkdocs.yml. A page missing from nav won't appear in the sidebar.

Drafts and search engines

An unwritten page starts with this front matter, above the # Heading:

---
noindex: true
---

It keeps the page out of Google while it still says nothing useful. The page is still reachable by URL, so you can send a colleague the link.

Delete those three lines when you finish the page, or it will never be found by the people it was written for. Nothing checks this for you.

The site's robots.txt deliberately allows crawling everywhere — a page that is blocked from crawling is never fetched, so its noindex is never read, and the URL can surface in results anyway.

Screenshots

Put them in docs/assets/<section>/. With a caption:

<figure markdown="span">
  ![Short description for screen readers](../assets/pos/cart.png){ width="700" loading=lazy }
  <figcaption>What the reader should notice in this picture.</figcaption>
</figure>
  • Compress before committing. A raw screenshot is 2–5 MB; aim for under 200 KB (pngquant, or export at ~1200px wide).
  • Always write the alt text — it's what a blind user hears, and what shows if the image fails to load.
  • Screenshots go stale faster than words. When a screen changes, re-shoot it.

Click-to-zoom is automatic — the glightbox plugin handles every image.

Videos

<div class="video">
  <iframe src="https://www.youtube-nocookie.com/embed/VIDEO_ID"
          title="What the video shows" loading="lazy"
          allow="accelerometer; clipboard-write; encrypted-media; picture-in-picture"
          allowfullscreen></iframe>
</div>

Use youtube-nocookie.com, not youtube.com — it avoids setting tracking cookies before playback, which keeps this site clear of cookie-consent rules. Start at a timestamp with ?start=90.

Callout boxes

!!! tip "Optional title"       ← a shortcut or a nicer way
!!! warning                    ← they could lose data or money
!!! danger                     ← cannot be undone
!!! info                       ← background, safe to skip

??? question "Collapsed"       ← troubleshooting; three ?'s means folded shut

Before you commit

  • [ ] Read it as someone who has never used ChouyLok.
  • [ ] Every step names a real on-screen label.
  • [ ] Screenshots match the current build, and are compressed.
  • [ ] Links work — mkdocs serve prints a warning for broken ones.
  • [ ] Nothing from the backend docs leaked in.

Khmer translations

Every page can have a Khmer twin, named with a .km.md suffix next to the English file:

docs/pos/taking-a-sale.md      ← English
docs/pos/taking-a-sale.km.md   ← Khmer

The language switcher appears in the header automatically. English is the default and is served at /; Khmer is served at /km/.

You do not have to translate everything before publishing

A page with no .km.md falls back to English inside the Khmer site, so it stays reachable and linked. Translate the pages shop owners actually open first — the POS pages, then products, then settings.

Notes:

  • Don't translate file names or folder names, only the .md content. The URL stays the same in both languages, so links keep working across the switcher.
  • Links inside a .km.md point at the English filename (../settings/users-and-roles.md). The plugin rewrites them to the Khmer URL at build time.
  • The UI strings — search box, "Next", "Back to top" — come from overrides/partials/languages/km.html. Fix wording there, not in a page.
  • Khmer needs more line-height than Latin because of stacked subscript consonants; that's handled in docs/stylesheets/extra.css under the Khmer section.

Search works less well in Khmer

The search engine (lunr.js) has no Khmer support, and Khmer is written without spaces between words, so it cannot reliably tell where one word ends. Searching a whole phrase as it appears in the text usually works; searching a single word inside a longer run of text often will not. Write clear headings — those are weighted most heavily and are what search will actually find.