Skip to content
GuideForDeveloperWith or without Foxden Admin

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 ​

TypeWhat it is forTitle
quickstartThe shortest path to a first resultA verb: "Install Foxden on one server"
tutorialA guided path that teaches by doing, start to finishA verb: "Send your first agreement for signature"
taskOne workflow, its steps, and what to do when it goes wrongA verb: "Invite people to your company"
conceptWhat something is and why it works the way it doesA noun: "Sharing levels"
referenceFacts to look up: settings, tools, commandsA noun: "Fennec settings"
troubleshootingSymptoms, causes and fixes"Fix ..." or "When ... fails"
outsiderFor someone outside the company: a signer, a form filler, a chat visitorA verb: "Sign a document"
releaseWhat changed in a releaseThe release name
sectionA section's front page: what is in it and where to startThe section name
homeThe 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.

Foxden is open source under Apache-2.0.