Writing Guide

These docs are for the people who use Applyfin, not for developers. Readers are recruiters and HR managers who arrive from search with a job to do.

This page is for whoever writes them.

One page per entry

Never create sub-pages. Every entry in the sidebar is one page, and everything about it lives on that page: what it is, what it relates to, and the steps for every task. content/1.getting-started/2.account.md is the shape to copy.

A page that feels long is not a reason to split it. Docus renders a table of contents from the headings, so a reader scans a page rather than clicking through a tree. Splitting one subject across pages is how two copies of the same steps get written, and one of them is wrong within a month.

Page shape

Every page opens with two paragraphs under no heading, then the headings below, in this order.

1. What it is — where the reader is and what the screen shows, in the app's exact labels. Readers arrive from search, not from the menu, so the first sentence has to place them.
2. Why it matters — what the thing holds together, what belongs to it, what it makes possible. This is the part readers cannot work out by clicking around, so it is the reason the page exists. It needs no heading of its own: the paragraph says what it is for.
3. ## Relations — the other models this one touches, as a short list. Readers lose the thread when a page names a department or a stage without saying what it does for them.
4. A heading per task, with its steps under it. Two to four words, named for what the reader is doing: ## Creating a department, ## Assigning users. These carry the instructions, so there is nowhere else for them to live.

Setup pages

Getting started works differently. Those pages are ordered work rather than a part of the app the reader returns to, and the reader is new, so they use three headings instead.

1. ## Requirements — the screens this covers, in the app's exact labels. A new reader does not yet know where anything lives, so name the screens before asking them to do anything on them.
2. ## Setup order — the sequence as numbered steps: bold action, dash, why it comes there. This is the part a setup page exists for. Say what is felt later when a step is skipped or done badly, such as a department set up carelessly, which every job opening afterwards inherits its defaults and its stages from.
3. A heading per task, with its steps under it, the same as everywhere else.

The introduction is a landing page and keeps its card grid. Errors and warnings is a reference page and follows neither shape.

Language

1. Only the app's own words. If the screen says Hiring Setup, the page says Hiring Setup. Invented synonyms send readers looking for a button that does not exist.
2. Never shorten a term. "Job opening" stays "job opening", never "opening". Shortened forms read fine in one sentence and become ambiguous in the next.
3. Bold what you click, plain what you read. Bold buttons, fields, tabs and menu items, copied exactly and including capitals. A screen name or a message you are only reading stays plain — bolding it makes it look clickable. Chain a path with a greater-than sign: Settings > Security.
4. Select, not click or tap. It covers a mouse, a keyboard and a touch screen. Never add the word "button": "Select Continue", not "select the Continue button".
5. Short sentences. Where two clauses are joined by , and, split them into two sentences. Long sentences are where vagueness hides.
6. No contractions. Write "it is" and "you are", not "it's" and "you're". This matches the existing pages.
7. No metaphors. No "container", "hub", "everything hangs off it". They sound explanatory and tell the reader nothing.
8. No stacked lists. "Nothing to publish, nothing to promote, nothing to measure" reads like a slogan and explains nothing. Write the sentence out instead, and let it carry the reason.
9. Concise headings. A heading is a label, not a sentence. Two to four words, no trailing punctuation.
10. Two or three words in bold. A bold label in a list or a step is a name, not a sentence. "Assign users", not "Assign users to departments and locations". Put the rest in the line after the dash. The one exception is a term that must not be shortened, such as "job opening".
11. Keep it simple. Write the way you would explain it to a new colleague on their first day. Use the plain word over the formal one: "use" not "utilise", "set" not "configure", "show" not "display". If a sentence needs a second read, rewrite it rather than punctuate it better.

Content

1. Be specific to Applyfin. If a sentence would fit a competitor's docs unchanged, it is not worth the reader's time. Everyone knows what a job opening is. Nobody knows what it does here.
2. Check every claim. If you cannot point at the page that proves it, flag it instead of shipping it. Wrong docs cost more trust than missing docs.
3. Orient before you instruct. The two opening paragraphs and ## Relations say what the thing is and what it touches. The task headings after them say how. Keep that order, because a reader who lands mid-page needs to know what they are looking at before they are told to select anything.
4. Say it once. Do not spell out what a sentence has already implied. "Your account is personal" says it belongs to you, so a clause adding that it does not belong to your employer is dead weight.
5. Say the non-obvious. That picking a department pre-fills most of the create steps is worth more than a description of the Create button.

Steps

These apply to the child pages, where the instructions live.

1. Say the goal first. "To publish the role, select Publish." The reader scanning the page needs to know what a step is for before they read what it does.
2. One action per step. If a step contains "and then", it is two steps.
3. End with what the reader should see. "The job opening now shows Published." Without it nobody knows whether it worked.
4. Follow the app's own steps. Where a screen runs a stepper, every step in it gets a step on the page. Never fold two of them into one.
5. No "first", "then" or "lastly". The numbers already carry the order.
6. Numbers for steps, bullets for everything else. Numbers mean order. Using them for a list of options tells the reader to work through it top to bottom.
7. Never write the same steps twice. Link to the heading that already has them. Two copies means one of them is wrong within a month.
8. Check for dead links before publishing. Renaming a page breaks every link pointing at it, and nothing warns you.

Pages and callouts

1. Frontmatter. Every page needs a title, a one line description and a navigation icon. Never put a colon in the description: it breaks the build.
2. ::note for an extra fact. Something useful that is not part of the main flow.
3. ::warning only when it hurts. It costs money, loses data, or cannot be undone. A warning on everything is a warning on nothing.
4. Screenshots sparingly. Only where seeing it makes it clear, such as a configuration screen. The app changes weekly and images go stale faster than anything else on the page.

Before you publish

Two checks, and both are made twice. The gap check asks whether everything that should be on the page is there. Line editing asks whether what is there is right. Make them in that order: there is no point polishing a sentence on a page that is still missing half its screen.

The gap check

Line editing fixes the sentences you wrote. It never finds the ones you did not. Those are the expensive omissions: a reply window that closes, a status the reader will meet on a filter, a button that only appears on one channel.

Read the page against the screens, twice. Walk the app surface the page covers and tick off every control, tab, status and enum against the page. The first pass finds what was never written. The second finds what the first pass added without connecting: a status list that now contradicts a filter, a new section that repeats one further down.

Report the gaps you found and the ones you are leaving. A gap check that reports nothing was not made. Where something is deliberately out of scope, name it, so the next writer does not think it was covered.

Line editing

The draft is not the page. Read it back sentence by sentence before you publish and make this pass, so the corrections do not arrive from a reviewer.

Make the pass twice. The first pass catches the invented claims and the clichés you wrote on the way to the point. The second catches what the first pass introduced, and the sentences you have stopped seeing because you wrote them. Nothing is finished after one pass.

Say what each pass found. When you hand the work over, report the two passes separately and name what each one caught. A pass that reports nothing either was not made, or was not made honestly. The second pass in particular should name what the first one broke: a split step that left the numbering wrong, a claim that lost its qualifier, a heading that stopped matching its section.

1. Delete any claim you cannot point at. Draft prose invents detail to round a sentence off. "In the same words each time" was written about evaluations, which take free text, so it was not true. If you cannot open the screen that proves a clause, cut the clause.
2. Name people the way the app does. User, contact, member, agent. Not "colleague", "team member" or "staff". The app's word is the one the reader will see on screen.
3. Cut every word that carries no fact. "Still readable weeks later" claims a number nothing supports. "Later on" says the same thing and claims nothing.
4. Say the sentence out loud. Anything you would not say to a colleague at their desk gets rewritten, not repunctuated.
5. Reflow the paragraph after every edit. Lines wrap at roughly 80 characters. A half-empty line in the middle of a paragraph is a leftover from the edit before.

Model relations

Get these right and the pages explain themselves. All of it is checkable in app/src/types/models/.

Recruiting

• A company has departments and locations. A job opening has one of each, plus one assignee.
• A department carries the defaults a new job opening starts from: category, skills, benefits, requirements, assessment criteria, application form and procedure. It also owns the stages applications move through, so the department decides the pipeline, not the job opening.
• A contact is a person, and holds more than their name: work history with each role, employer and tenure, plus the signals Applyfin enriched them with. A talent pool is a named group of contacts, optionally tied to one job opening that is picked at creation and never changes. Each contact in it is a member, and the same person can be a member of several talent pools. On a talent pool with a job opening every member is assessed against that job; one without is a plain list.
• An application belongs to one job opening. It carries the contact, the department, the location, its current stage, an assignee and its evaluations.
• An application carries both an assessment and its evaluations, and they are not the same thing. An assessment is the AI's judgment of the person against that job opening's assessment criteria, scored out of 100. There is one per person per job opening, shared by the application and every talent pool member for that pair. An evaluation is a form a colleague fills in, following an evaluation template, and an application can have several.

Sourcing

• A promotion belongs to one job opening. It is bought as a listing on an external channel.
• A feed distributes job openings to a channel on its own terms: managed or contract, with its own budget and medium.
• A career page is built from pages and published on its own.
• Where an application came from is recorded as either a promotion or a source. Results are reported per job opening and source.
• A conversion is bound to a stage and counts the applications that reach it. A tracking account ties a channel to those conversions, which is how a hire is reported back to the channel that paid for it.
• A source is a named place applications come from, and carries its own count.
• A consent manager is the consent banner published on the career page, with its own purposes and its own publish state.
• Career page metrics count visits, actions per visit, bounces and converted visits against three goals.

Communication

• An inbox has one channel: email, Outlook, WhatsApp or LinkedIn.
• A conversation belongs to one inbox and one contact. It holds the messages and is assigned to a user or an agent.

Automation

• An action runs on the stages you attach it to.
• An agent works inside an inbox and can take a conversation itself.
• The AI assistant is a chat that can call the same tools you would use by hand.

Administration

• Promotions and plan upgrades are bought from the company balance as orders, and paid through Mollie.
• An API token gives an outside system access to the company.
• Notifications reach a user by the channels they chose themselves.

Across the whole platform

• A view is a saved list: its filters, sort, grouping and visible columns. This is why job openings and applications have a view in their address.
• A label can be attached to any record, and comments, activity, errors and warnings work the same way.

Example

content/2.recruiting/1.job-openings.md is the reference for the shape above.