--- url: https://docs.codefox.ai/contribute/write-docs.md --- # 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 1. 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. 2. Open the app and do the task yourself, so every step and every on-screen word is one you saw. 3. 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. ```yaml --- 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`: `connected` when the page assumes Foxden Admin is connected, `alone` when it is about an app running by itself, `both` when it reads the same either way. * `needs`: what has to be set up first, such as `Admin`, `email` or `an 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 by `scripts/generate.mjs` on pages it writes. Never write one of those pages by hand: change the code it reads instead. ## Templates A task page: ```md # 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.` and `i.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 ```bash cd docs/portal npm ci npm run dev # preview at the address it prints npm run check # generated pages up to date, writing rules, build ``` `npm run check` names each problem as `file:line`. Fix the page, not the rule.