# Article contribution and writing standards This is the bar for wiki articles. It's here so readers find what they need quickly and contributors know what good looks like before they start. Read it end to end before you write anything for the wiki, and refer back to it during review. It's important these steps are followed — articles that don't meet the bar won't be published. ## Who this is for and the bar This guide applies to anyone contributing content to the Wageloch user guides — support, implementation, product, engineering, or anyone else asked to write an article. It does not apply to engineers maintaining the wiki platform itself; that material lives in the repository's `docs/` folder. The standards below apply to every article: new pages, rewrites of existing pages, and edits significant enough to need a `changeSummary` bump. There is no "draft quality" exception, no "I'll fix it later" exception, and no "the support team will tidy it up" exception. > [!IMPORTANT] Submissions that do not meet this standard are rejected > > The reviewer's job is to verify the article meets the bar, not to rewrite it for you. An article that ignores this guide will be sent back unmerged. Two rejections on the same article and it is closed; rewrite from scratch or hand it off. ## Before you write Three checks, in order. Skip any of them and you are wasting your time and the reviewer's. 1. **Confirm the article does not already exist.** Search the wiki for the topic. If a page already covers it, your job is to improve that page or split it — not to add a parallel article that competes with it. Duplicates are rejected on sight. 2. **Scope the article to one job.** A reader arrives with one question. An article answers one question. If you are writing "and also", "additionally", or "if you are an administrator, see..." you are writing two articles. Split it before you submit. 3. **Identify the audience.** Employee, manager, payroll administrator, or system administrator. The audience determines the vocabulary, the level of detail, and what you can assume the reader already knows. An article aimed at "everyone" is aimed at no one. Before you write the first paragraph, write a one-sentence statement of success: *"After reading this, the reader can ____."* Keep it visible while you write. Every paragraph that does not move the reader toward that outcome is a paragraph to cut. ## The structure every article follows This is not a suggestion and there are no per-author exceptions. Articles that deviate without a reason you can defend in the PR are harder to scan, harder to maintain, and disproportionately likely to be the ones we get complaints about. ### Title Sentence case. Descriptive. No marketing. - Do: `Approve a pay run` - Do: `Set up multi-factor authentication` - Do not: `Approving Pay Runs Made Easy` - Do not: `The Ultimate Guide to MFA` Preserve official product casing where it appears in the UI (`My Roster`, `Log Book`, `Shift Swap`). Everywhere else, sentence case. ### `previewText` One sentence. It tells the reader what the article is *and* how they will know it answers their question. It appears in cards, search results, and link previews. It is the difference between someone clicking through and bouncing. - Do: `"How to approve a pay run, including the pre-approval checks that prevent a costly rollback."` - Do not: `"This article explains how to approve a pay run."` (says nothing the title does not already say) - Do not: `"Pay run approval"` (a label, not a description) ### Opening paragraph State the problem and the outcome in two or three sentences. No throat-clearing. No "In this article, we will explore...". The reader does not need to be welcomed; they need to be helped. Articles that open with throat-clearing are rejected. ### Body H2 sections for the main steps or topics. H3 only when an H2 genuinely needs sub-sections. Do not skip levels (no H4 under an H2). Do not use bold as a substitute for a heading. For procedural articles, use the predictable flow: - `## Before you start` — prerequisites, permissions, things to check first - `## How to ` — the actual steps - `## Troubleshooting` — only if there are real, common failure modes - `## What happens next` or similar — only if the reader needs to know ### Conclusion Most articles do not need one. If yours does, it is a single short paragraph pointing to the next logical action or related page. It is not a summary of what you just wrote — the reader read it. ## Writing style These are the rules. They are not negotiable and they are not stylistic preferences. - **Short sentences.** If a sentence runs over two lines on screen, it is two sentences. Cut it. - **Active voice.** "Select Save" not "Save should be selected". Passive voice makes instructions vague and is the single most common rejection reason. - **Second person.** Address the reader as "you". Not "the user", not "they", not "one". - **Present tense.** "The roster opens" not "the roster will open". - **Australian English.** "Colour" not "color", "organise" not "organize", "centre" not "center". This is a Wageloch product; we are in Australia. - **No jargon without explanation.** If you must use an internal term ("award interpretation", "departmental mapping"), give a one-line definition the first time it appears. - **No marketing tone.** This is technical documentation, not a brochure. Words to delete on sight in body copy: *seamless*, *powerful*, *robust*, *world-class*, *unlock*, *empower*, *leverage*, *streamline*. - **No walls of text.** If a paragraph is more than four lines on a normal screen, it is too long. Break it. Add a heading. Use a list. Concrete contrast: > Do: To approve the pay run, open Payroll, select the current period, and click **Approve**. > > Do not: When a pay run reaches the final stage of processing, it may be approved by the relevant administrator through the payroll module, where the approval action is made available once all prerequisite validations have been completed. For procedural steps, format clickable or tappable controls in **bold** and use consistent verbs: *Open*, *Select*, *Click*, *Tap*, *Enter*, *Save*. One action per step. Steps that combine three actions in one sentence will be sent back. ## Frontmatter cheat sheet Every article starts with a YAML frontmatter block. These are the supported keys. **Do not invent new keys** — anything the parser does not recognise is silently ignored, and that is how broken metadata reaches production. ```yaml --- title: Approve a pay run previewText: "How to approve a pay run, including the pre-approval checks that prevent a costly rollback." updatedAt: 2026-05-19 author: Payroll Team changeSummary: "Added pre-approval checklist and rollback note." tags: - payroll - approvals sidebarOrder: 30 private: false incomplete: false experimental: false advanced: false --- ``` What each one does: - **`title`** — the human-readable title. Required in practice; omit it and the page is named after the folder, which is almost never what you want. - **`previewText`** — one sentence (see above). Required in practice. Without it, the excerpt is auto-generated from the first 180 characters of the body, which is almost always worse than what you would write deliberately. - **`updatedAt`** — the date you last meaningfully edited the article. Required when you make a substantive change. Use `YYYY-MM-DD` or a full ISO-8601 datetime; the parser accepts both. - **`author`** — your name, or a team name (`Payroll Team`, `Support Team`). Use a team name when ownership is collective. - **`changeSummary`** — a one-line description of what changed in this revision. Powers the "latest updates" feed. Without it, the feed falls back to the git commit subject, which is usually less useful. - **`tags`** — a YAML list of lowercase, hyphenated topical tags. Three to six is a good target. Tags drive search relevance and the related-articles cards. Reuse existing tags before inventing new ones. - **`sidebarOrder`** — an integer. Lower numbers appear earlier. Use it to put a landing page or "start here" article above its peers. Omit it when alphabetical order is correct. Flag fields (booleans — `true` only, exactly; anything else is treated as false): - **`private: true`** — Hidden from the sidebar, category cards, related-article cards, and from the article list and search APIs. Still loadable by direct URL. Use for link-only material like this guide, internal-only references, or drafts you want to share with reviewers before going public. - **`incomplete: true`** — Shows a work-in-progress banner. Use only briefly. An article that has been `incomplete` for a month is unfinished work shipped to production. - **`experimental: true`** — Shows an experimental-feature banner. Use when documenting a feature that is in pilot or behind a flag. - **`advanced: true`** — Renders the linked-internal-pages cards at the bottom of the article. Use on hub pages that exist to direct readers to deeper material. > [!CAUTION] Flag hygiene > > Do not ship `private: true` on a page that is meant to be public. The article quietly disappears from navigation and search; you will not notice until someone asks why they cannot find it. Equally, do not ship `incomplete: true` and forget about it — a permanent "work in progress" banner trains readers to ignore banners. ## Callouts Callouts exist to draw attention. If everything is a callout, nothing is. Use them deliberately. Articles that carpet-bomb the page with callouts are rejected. Use the blockquote form for short, single-paragraph callouts: ```md > [!WARNING] Locked pay period > > Do not run finalisation while imports are in progress. ``` Use the block form when the callout needs multiple paragraphs, lists, or code: ```md [!IMPORTANT] Before you proceed You must complete all three of the following before approving: - All pay groups closed - Exception report cleared - Integrations finished syncing [/!IMPORTANT] ``` When to use which marker: - **`NOTE`** — neutral asides the reader should not skip but does not need to act on. - **`INFO`** — context that changes how the feature behaves (permission-gated steps, configuration-dependent screens). - **`TIP`** — optional improvements, shortcuts, faster paths. - **`IMPORTANT`** — prerequisites or constraints the reader must satisfy. If they ignore this, the steps will not work. - **`WARNING`** — actions with real consequences. Money, time, or trust will be lost if the reader is careless. - **`CAUTION`** — irreversible actions. Data loss, settings that cannot be undone, integrations that cannot be replayed. - **`SCREENSHOT`** — a placeholder for a screenshot that has not been captured yet. Include a clear description of what should be in the frame. Rules: - One callout per section. Two if both are genuinely earned. Three is almost always wrong. - Never use a callout where a sentence would do. - Place the callout directly before or after the step it applies to. A WARNING three sections away from the action it describes is invisible. ## Links Internal links use the `/guides/...` path. Do not use relative paths and do not use absolute domain URLs for internal pages. - Do: `[Set up MFA](/guides/basics/security/multifactor-auth)` - Do not: `[Set up MFA](../security/multifactor-auth)` - Do not: `[Set up MFA](https://guides.wageloch.com.au/guides/basics/security/multifactor-auth)` Other link rules: - **No "click here".** Link text describes the destination: `[the approval checklist](...)`, not `[click here](...)`. - **Do not repeat the same destination link.** Link the first useful mention. After that, the reader knows the page exists. - **External links** point to durable URLs (an organisation's official documentation, a legislative source, a release notes page). Avoid blog posts, third-party tutorials, or anything that may disappear. - **Verify every link before submitting.** Broken internal links are a top rejection reason and they are entirely avoidable. ## Images and screenshots A good screenshot saves the reader minutes of work. A bad screenshot adds noise and ages badly. The bar is high. A useful screenshot is: - **Cropped tightly** to the thing you are showing. Not the whole browser window. - **Current.** Matches the UI the reader will see today. If the UI has changed, recapture. - **Annotated when it helps.** A single arrow or box on the control being discussed. Not a rainbow of markup. - **Redacted of customer data.** Real names, real wages, real ABN numbers — never. Use the test environment or a clearly fictional dataset. - **Free of UI chrome that does not matter.** Tab bars, bookmarks, OS taskbars, your other open windows: crop them out. - **Saved with alt text that describes the image.** Not "screenshot.png". Not "image". Alt text is what assistive tech reads aloud and what shows when the image fails to load. File naming and placement: - Lowercase, hyphenated, no spaces: `approve-pay-run-confirmation.png`, not `Screen Shot 2026-05-19 at 10.42.png`. - Place screenshots in `public/wiki-assets/imported-wiki//` where `` is the last segment of the article's URL. - Reference them in markdown as `/wiki-assets/imported-wiki//.png`. If you need a screenshot but have not captured it yet, use the placeholder. Do not ship the article without something in its place: ```md [!SCREENSHOT] Pay run approval confirmation Capture the confirmation banner with the pay period dates and approver name visible. Use the demo company; do not include real employee names. [/!SCREENSHOT] ``` ## Video embeds The renderer auto-embeds links from a small allowlist of providers: - YouTube (use the privacy-enhanced `youtube-nocookie.com` form where possible) - Vimeo - Loom - Dailymotion Rules for video: - **Text first, video second.** Video is supplementary. The article must convey the information in writing for readers who cannot or will not play a video. - **One video per article, at most.** If you need more, you are writing a video script, not an article. - **Keep videos short.** Two minutes is a generous upper bound for a how-to. - **Do not embed video as a substitute for a screenshot.** Static UI is documented with static images. ## Naming, slugs, and file layout Articles live at `content///index.md`, or one level deeper for sub-categorised material: `content//_{//index.md`.

Slug rules:

- Lowercase letters, digits, and hyphens only.
- No spaces, no underscores, no special characters.
- Match the slug to the title, but shorter is fine: `approve-a-pay-run` for `Approve a pay run`.

### Granularity: when to split an article

Long single articles fail readers. Someone arrives from search wanting one answer; they should not have to scroll past four other topics to reach it. When a topic spans multiple audiences or multiple distinct user tasks, it stops being one article and becomes a sub-category of focused child articles.

> [!IMPORTANT] Threshold rule
>
> If an article meets **any** of the following, split it before submitting. These are not soft guidelines.
>
> - More than **five distinct H2 sections** that each cover a separate user task.
> - More than **~1,500 words of body content** for a how-to or walkthrough. (Reference material can be longer; procedural articles cannot.)
> - More than **one audience** (employee, manager, payroll admin, system admin) addressed in the same article. This one is non-negotiable — audiences always split.

The failure mode the rule prevents is simple: a reader who only needs *one of the things in your article* has to scroll past everything else. Readers landing on a help article rarely want the whole topic — they want the bit that answers their question.

**The pattern: sub-category with task-scoped children.** Create a folder at `content///` and place each audience or task in its own `index.md` underneath. The canonical example in this repo is the **Mobile App** content:

```
content/mobile-app/
├── index.md (short hub — 60 lines)
├── employees/
│ ├── index.md (audience hub — 83 lines)
│ ├── clocking/index.md
│ ├── payslips/index.md
│ ├── leave/index.md
│ ├── shift-swaps/index.md
│ └── ...
└── managers/
├── index.md
└── ...
```

Note what the structure does: the topic-level hub orients the reader, the audience hubs route them, and each task gets its own URL. Nothing was written as a single 2,000-line `mobile-app/index.md` — that would have been wrong, and it would have been rejected.

**What "splitting" actually means.** Not "cut the article in half at a heading". Re-scope. Each child article must stand on its own as the answer to one reader's question, with its own `title`, its own `previewText`, its own opening that states the problem and outcome, and its own conclusion if it needs one. A child article that requires reading its sibling to make sense is not split, it is mutilated.

**What a sub-category hub `index.md` is, and is not.** A hub page exists only when the topic needs a landing page that orients the reader before they pick a child. If the children are self-explanatory from their titles, the auto-generated child list on the parent category page is enough and a hub `index.md` is unnecessary. When a hub is written, it is a short overview — one or two paragraphs, optionally a list of the children with a sentence each. It is **not** the original long article shoved up a level with the steps still in it.

### When to merge two articles

- They answer overlapping questions and the reader cannot tell which page to start on.
- One is a thin stub that exists only because someone wanted a separate URL.

## Common rejection reasons

In rough order of frequency. None of these are subtle. Each one is a verdict, not a hint: if your article does any of these, it will not be merged.

- **Wall of text, no headings.** Three screens of unbroken paragraphs. Rejected — add H2/H3 sections and resubmit.
- **One article doing the job of several.** Article serves multiple audiences or multiple distinct tasks in one file. Rejected — break it into a sub-category with task-scoped child articles.
- **Marketing tone.** "Wageloch's powerful rostering engine seamlessly empowers your team..." — rejected. This is the wiki, not a brochure.
- **Passive voice throughout.** "The approval is performed", "the form is submitted", "it should be ensured that...". Rejected. Put a subject in front of every verb.
- **Missing or vague `previewText`.** A label, a rephrase of the title, or nothing at all. Rejected — write a real one-sentence summary.
- **No `updatedAt` on a substantive change.** Rejected. The latest-updates feed cannot tell that your edit happened, so as far as readers are concerned the article is unchanged.
- **Broken internal links.** `/guides/some-old-path` that 404s. Rejected — verify every link before submitting.
- **Speaks about the company in third person.** "Wageloch users can..." — rejected. The reader *is* the user. "You can..."
- **Customer data visible in screenshots.** Immediate rejection, no resubmission until every frame is redacted, recaptured, or replaced with the demo company.
- **Screenshot of a screenshot.** A phone photo of a monitor. Rejected — capture the screen directly.
- **TODOs left in the body.** ``, `[insert example here]`, `lorem ipsum`, `xxx`. Rejected. Finish the article before submitting it.
- **Callout abuse.** Six callouts on one page, none of them earned. Rejected — strip them back to one per section.
- **Embedded video with no text equivalent.** A reader who cannot watch the video should still be able to do the thing. Video-only articles are rejected.
- **Duplicates an existing article without superseding it.** Rejected on sight. If a page already covers this, improve that page or replace it. Do not create a parallel article.
- **Inconsistent capitalisation.** `My roster`, `My Roster`, and `my roster` all in the same article. Rejected — pick what the UI uses and stick to it.
- **`private: true` on a public page.** Quietly hides the article from navigation and search. Almost always a mistake. Rejected.
- **`incomplete: true` shipped and forgotten.** Either finish it or unflag it. A "work in progress" banner that lives in production for a month is rejected on its next touch.

## Submission and review

The publishing flow:

1. Write the article in the wiki editor or directly in markdown if you are comfortable with it.
2. Preview it. Read it back as if you were the reader who arrived from a search result.
3. Run through the checklist below.
4. Submit through the editor's publish flow. This creates a branch and a pull request against the wiki repository.
5. A reviewer (currently a senior team member or the wiki maintainer) reads the PR and either approves it, requests changes, or rejects it.

What review will check:

- The structure and style rules in this guide.
- Frontmatter sanity — required fields present, no typos, no invented keys.
- Links — internal links resolve, external links are durable.
- Screenshots — recent UI, no customer data, sensible file names and alt text.
- Voice and tone — active, second person, no marketing language.
- The "common rejection reasons" list above.

If review comes back with changes or a rejection:

- **Read the feedback in full before responding.** Half-reading the comments and rebutting them line by line is how review cycles turn into arguments.
- **Revise the article.** Do not argue that the existing draft was fine. If a reviewer cannot follow the article, that is the article's fault.
- **Ask for clarification only when feedback is genuinely ambiguous.** Most review feedback is concrete and actionable on its own.
- **Resubmit, or withdraw.** A revised article goes back through the same flow. If you do not agree with the feedback and do not want to revise, withdraw the PR.

> [!WARNING] Arguing back is not a path forward
>
> The PR comments are not a debate. A rejected article is revised, or it is withdrawn. Re-litigating the standard, demanding the reviewer prove the rule, or pushing the same draft back with a longer comment will close the PR and any further submission on that topic will be reassigned.

> [!TIP] Pre-submit checklist
>
> Run through this before you hit submit. Two minutes here saves a review cycle.
>
> - Title is sentence case and descriptive.
> - `previewText` is one real sentence.
> - `updatedAt` is set to today.
> - `changeSummary` describes the change.
> - All H2/H3 headings are in order, no skipped levels.
> - No ``, `[TBC]`, or placeholder text.
> - Every internal link resolves.
> - Screenshots are current, cropped, and clean of customer data.
> - Read it top to bottom as a reader. Does it answer the question in the title?

## A worked example: before and after

The same content, written badly and then rewritten to standard. Both fragments describe the same procedure.

### Before — rejected

> # Approving Pay Runs in Wageloch — Complete Guide
>
> This article will walk you through everything you need to know about Wageloch's powerful pay run approval functionality. Pay run approval is a critical part of the payroll process that ensures the integrity of your data and the satisfaction of your employees. When the pay run is ready to be approved by the relevant administrative user, it can be approved through the payroll module. There are some things that should be considered before approval is initiated. The user should ensure that the pay groups are closed and any exceptions have been resolved, also the integrations need to have finished. Then, the user can navigate to the payroll section, click on the current pay run, and click the approve button. If something goes wrong it might be possible to roll back but this is risky and should be avoided.

Why this is rejected, line by line:

- **Title.** Mixed case with "Complete Guide" tacked on. Sentence case, descriptive, no fluff: this fails on all three.
- **First sentence.** "This article will walk you through everything you need to know about Wageloch's powerful pay run approval functionality" is throat-clearing plus marketing tone. It tells the reader nothing the title did not already say. Cut entirely.
- **Second sentence.** "A critical part of the payroll process that ensures the integrity of your data and the satisfaction of your employees" is brochure copy. The reader is not deciding whether to use the feature — they are trying to use it.
- **Third sentence.** "When the pay run is ready to be approved by the relevant administrative user, it can be approved..." is passive voice twice in one sentence and the subject is missing entirely. The reader cannot tell who does what.
- **No structure.** One paragraph for a procedure that has prerequisites, steps, and consequences. No `Before you start`, no numbered steps, no `Troubleshooting`.
- **"The user should ensure"** — third person and passive. The reader *is* the user. Address them directly.
- **Steps mashed together.** "Navigate to the payroll section, click on the current pay run, and click the approve button" is three actions in one sentence with no numbering and no bold for the UI controls.
- **Consequence is hidden in a soft phrase.** "If something goes wrong it might be possible to roll back but this is risky and should be avoided." Rollback is expensive and visible to staff. That belongs in a `WARNING`, not buried in the closing clause of a paragraph.
- **No frontmatter shown.** No `previewText`, no `updatedAt`, no `changeSummary`, no tags. The article would not appear meaningfully in search or the updates feed.

### After — meets the bar

```md
---
title: Approve a pay run
previewText: "How to approve a pay run, including the pre-approval checks that prevent a costly rollback."
updatedAt: 2026-05-19
author: Payroll Team
changeSummary: "Rewrote approval steps and added rollback warning."
tags:
- payroll
- approvals
---

# Approve a pay run

Approving a pay run finalises the period and triggers integration exports. Get it wrong and rolling back is slow, manual, and visible to staff. Run the checks below first, then approve.

## Before you start

- All pay groups are closed.
- The exception report is empty (or every exception has a documented reason).
- All integrations show "Sync complete" for the current period.

> [!WARNING] Rollback is expensive
>
> Once approved, undoing a pay run requires manual reversal of exports and may delay the next pay cycle. Confirm the checks above before clicking **Approve**.

## How to approve

1. Open **Payroll** > **Current pay run**.
2. Review the totals against the previous period. Investigate anything more than ten percent off.
3. Select **Approve pay run**.
4. Confirm the dialog by selecting **Approve**.

The status changes to **Approved** and integration exports begin within a minute.
```

Why this works: title is sentence case; the opening states the problem and the stakes in two sentences; structure is predictable (`Before you start` + `How to approve`); steps are numbered, one action each, with bold UI controls; the `WARNING` is earned because rollback genuinely is expensive; no third person, no passive voice, no marketing language; frontmatter is complete.

That is the bar. Hold yourself to it before review has to.}

Wageloch User Guides

Browse by category

Mobile App