Write a docs page
This page lets you add or change a page on this site so it reads like every other page. The site lives in docs/portal in the Foxden repository, and npm run check there holds every page to the rules a machine can check.
Before you write
- Find the code the page is about. Every fact on a page comes from the code, the running app or the person who owns the app, never from an older document.
- Open the app and do the task yourself, so every step and every on-screen word is one you saw.
- Pick the page's type from the table below. A page is one type; a page that wants to be two is two pages.
Page types
| Type | What it is for | Title |
|---|---|---|
quickstart | The shortest path to a first result | A verb: "Install Foxden on one server" |
tutorial | A guided path that teaches by doing, start to finish | A verb: "Send your first agreement for signature" |
task | One workflow, its steps, and what to do when it goes wrong | A verb: "Invite people to your company" |
concept | What something is and why it works the way it does | A noun: "Sharing levels" |
reference | Facts to look up: settings, tools, commands | A noun: "Fennec settings" |
troubleshooting | Symptoms, causes and fixes | "Fix ..." or "When ... fails" |
outsider | For someone outside the company: a signer, a form filler, a chat visitor | A verb: "Sign a document" |
release | What changed in a release | The release name |
section | A section's front page: what is in it and where to start | The section name |
home | The site's front page |
One page holds one workflow. The smaller jobs inside it are sections of that page, not pages of their own. Put troubleshooting at the end of the task page it belongs to; give it a page only when it spans several tasks.
Front matter
Every page starts with front matter. title and type are required; the rest describe who the page is for, and the line above each page shows them.
---
title: Invite people to your company
type: task
order: 20
who: Owner
mode: connected
needs: email
---order: where the page sits in its section's menu, lowest first. Leave gaps (10, 20, 30) so a page can go between.who: who the page is for. In the app, the words the screens use: Can use, Can manage, Team lead, Owner. Outside it: Operator for the person who runs the server, Developer for someone building on Foxden or changing its code, Everyone for any reader. Never a stored role name.mode:connectedwhen the page assumes Foxden Admin is connected,alonewhen it is about an app running by itself,bothwhen it reads the same either way.needs: what has to be set up first, such asAdmin,emailoran AI key.menu: false: keeps the page out of the menu. Outsider pages use it; the emails and screens those people see link to them.generated: set byscripts/generate.mjson pages it writes. Never write one of those pages by hand: change the code it reads instead.
Templates
A task page:
# Invite people to your company
One sentence: what this page lets you do, and for whom.
## Before you start
What has to be true first, as a short list.
## Invite someone
1. Open **People**.
2. Select **Invite**.
3. ...
## Troubleshooting
### The invitation never arrives
Cause, then what to do.A concept page opens with one paragraph that says what the thing is, then explains it in short sections, and ends with links to the task pages that use it. A section's front page says in one sentence what the section covers, then lists its pages, the first one to read on top.
Words
- Write to the reader as "you", in the present tense and the active voice.
- The first line under the title says what the page lets you do.
- One action per numbered step. Put the result of a step in the same step, after the action.
- Write words from the screen in bold, exactly as the screen shows them: Save, People.
- Task titles start with a verb; concept titles are nouns. Never title a page "Overview", "Introduction" or "How it works".
- Call the apps by their names: Fennec, Arctic, Corsac, Pampas, Culpeo, Cape and Library. Write "Foxden Admin" the first time on a page and "Admin" after it.
- Say levels the way the screens say them: a person can use an app or can manage it, a Team lead, the Owner. The words come from
packages/shared/src/access/copy.ts. - Leave out
simply,just,please,easy,currently,via,e.g.andi.e.. Never use em dashes. - Link text names where the link goes, usually the page's title. Headings hold no links.
- Leave out anything that is not released, anything only Codefox uses, and the name of any client or person.
Check and preview
cd docs/portal
npm ci
npm run dev # preview at the address it prints
npm run check # generated pages up to date, writing rules, buildnpm run check names each problem as file:line. Fix the page, not the rule.