Documentation style guide

This is the house style for the Line20 help centre. It exists so every page reads as if one careful person wrote it, and so an automatically drafted page can be measured against a clear standard before a human approves it.

If you are writing or reviewing a help page, read this first. If a draft does not follow it, that is the thing to fix.

Every page is one of four kinds

We follow Diátaxis, which sorts documentation into four kinds by what the reader is trying to do. Decide which kind a page is before you write a word — mixing two kinds in one page is the most common way help goes wrong.

• Tutorial — learning by doing. A lesson that takes a newcomer end to end the first time, so they arrive somewhere and feel capable. It is you, teaching. Example: Getting started.
• How-to guide — achieving one task. A recipe for a reader who already knows roughly what they want and needs the steps. It starts from a goal and ends when the goal is met. Example: How to issue an invoice.
• Reference — looking something up. A dry, complete description of the machinery: fields, statuses, what each value means. The reader consults it; they do not read it through.
• Explanation — understanding why. Background that steps back and describes how a part of Line20 works and the thinking behind it. It answers "why", not "how".

How to write it

• Write British English. Organise, finalise, centre, licence (noun), colour — not the American spellings. This is a hard rule, checked in review.
• Address the reader as "you". Never "the user". You are speaking to one person doing one job.
• Say it plainly, and give one concrete example. Name the thing that changed and what it does, not the mechanism underneath. Prefer a real example — an actual field name, a value they will type, what they will see on screen.
• Use sentence case for headings ("How to issue an invoice", not "How To Issue An Invoice"), matching the page titles already in this centre.
• Keep steps as a numbered list, one action per step, in the order the reader performs them. Reserve bullet lists for things that are not sequential.
• Use callouts sparingly — <Callout> for an aside, <Callout type="warn"> for a genuine "you cannot undo this" caution. If every paragraph is a callout, none of them is.

Use the product's own words

Line20 keeps a few terms deliberately distinct, and the help must match what the reader sees on screen — including where English and Dutch do not line up:

So the Dutch word product means the thing you make, and a Dutch reader billing a customer is working with artikelen. Never translate these words literally — use the label that appears in the interface for that language. When in doubt, open the screen the page describes and copy the word Line20 uses there.

Keep the help brand-blind: it documents Line20 itself, never a particular customer's shop or branding.

How translations work

• English is the source. Write the page in English first, under content/docs/en/.
• Dutch lives alongside it under content/docs/nl/, one file per page, same slug.
• An untranslated page falls back automatically. If a Dutch page does not exist yet, a reader on its Dutch URL sees the English content with a short "not yet translated" notice — nothing 404s. So it is fine to ship an English page before its Dutch twin; it just reads in English until someone translates it.
• Every page must appear in every locale's meta.json navigation list, or a test fails — even a page that only has an English file. That is what puts an untranslated page in the Dutch sidebar (landing on the fallback notice) rather than leaving it reachable only by guessing the URL.
• Links inside a fallback page point at the English tree. A page served as an English fallback keeps its own /docs/... links, so a Dutch reader who follows one leaves /nl/. That is an accepted limitation of raw fallback content — one more reason to translate a page rather than leave it falling back for long.