Writing help texts

Help texts are not in the Google Sheet. Each profile has one hand-written file in the schemas repository, help/docs.<profile>.json, keyed by field id. The format is defined in help/help.schema.json; the help file format page describes it.

The four levels

The editor shows help at four levels. Each level must add something the previous one does not have.

Level	Key	Where it shows	Write
1	tooltip	On hover or focus of the (?) icon	One line, no full stop. What the field is.
2	short	Under the field	One or two sentences: what to fill in.
3	extended	Help panel	Why the field matters and how to fill it in well: scope, choices, common mistakes.
4	details	Help panel, under "More", closed by default	Examples, notes on edge cases, links.

Do not write facts that follow from the schema: required or not, how many values, the vocabulary, the format or pattern, the identifier schemes, the export property. The editor and the reference derive those from the schema, so they cannot go out of date. details.mapping in particular is generated by the build; never write it by hand.

Level 1: tooltip

• A noun phrase or a short instruction: "The licence for this distribution".
• Different from the short text. If you have nothing to add to the label, leave it empty.

Level 2: short

• Tell the user what to enter: "Give the name of the organisation that publishes the dataset."
• Start with a verb or "The ...". Avoid "This field ...".
• At most two sentences.

Level 3: extended

• Explain why the field matters, which value to choose when several fit, and how it relates to other fields ("Use Dataset curator for the person who maintains the data").
• Do not start by repeating the short text. The lint warns when one contains the other.
• Plain text. A blank line starts a new paragraph.

Level 4: details

"details": {
  "examples": [
    { "value": "Delpher newspapers 1618-1995" },
    { "value": "Dataset 1", "quality": "bad", "note": { "en": "Says nothing about the content." } }
  ],
  "notes": { "en": "If the dataset has no official name, ..." },
  "seeAlso": [ { "url": "https://www.w3.org/TR/vocab-dcat-3/#Property:resource_title", "label": { "en": "DCAT: title" } } ]
}

• examples: values as a user would type them. A structured field can have a JSON value. Mark counter-examples with "quality": "bad"; the editor lists them under "Avoid". Add lang to show an example only in one editor language.
• notes: edge cases and conventions.
• seeAlso: links to the standard or guidance the field comes from.

Style

• Plain, concise English. Address the user directly ("Give ...", "Use ...").
• No marketing tone and no em dashes. One idea per sentence.
• English first. Other languages (nl, fr, de) may stay empty; the editor falls back to English.
• No placeholder text. Texts marked "AI-generated placeholder" must be replaced by reviewed text before release; the lint counts them.

Profile help

general holds the help shown when no field is selected: title, short and extended. The reference page of the profile uses short and extended as its introduction.

Generic help for the sub-fields of a type (the name of an Agent, the URL of a Reference) goes in help/docs.type-library.json. A profile file can have an entry for a type-library id, but the id is the same wherever the type is used, so the text applies to all those places; the lint reports such entries as foreign.

Workflow

1. Build (./build-local.sh or ./build.sh). The help step, GenJSONSchema/postprocess_docs_schema.py, adds an entry for every new field id, refreshes label and path from the schema, and keeps everything you wrote. label and path are overwritten on every build; change them in the sheet.

2. Edit help/docs.<profile>.json. Editors that understand JSON Schema check the file as you type, through its "$schema": "./help.schema.json".

3. Run the lint and fix what it reports:

   python3 scripts/lint_help.py --schema-dir output
   python3 scripts/lint_help.py --schema-dir output --only repeat      # one kind of warning

4. Commit the help files.

The help step also runs without the sheet, against a published bundle:

python3 GenJSONSchema/postprocess_docs_schema.py \
  --schema-dir <monorepo>/app/sidedoc-frontend/public/schemas/0.2.4 --out-dir /tmp/help
python3 GenJSONSchema/postprocess_docs_schema.py --schema-dir <bundle> --check   # is help/ up to date?

Lint messages

The lint fails (exit code 1) only when a file does not match the format. Everything else is a warning; --strict (or HELP_LINT_STRICT=1 in build.sh) makes warnings fail too.

Warning	Meaning
repeat	extended repeats short: equal after normalising, or one contains the other.
tooltip	tooltip is the same as short.
no-short	A field of the schema has no English short text.
stale	The help has an id the schema does not have (a removed field). Move the text or delete the entry.
foreign	An id of another profile or of the type library.
mapping	details.mapping written by hand.
legacy	An entry under x-legacy-unmatched: an old path-keyed entry that matches no field.
placeholder	Text still marked as an AI-generated placeholder.

x-legacy-unmatched exists because older help files were keyed by path (fieldsByPath). The help step converted them to ids; entries for paths that no longer exist (mostly old section headings) were kept there so no text was lost.

How help reaches the editor

1. The build writes output/docs.<profile>.json: the help source plus the generated details.mapping, with a versioned $id. It also sets x-sidedoc.docsSchemaUrl in each profile to /schemas/<version>/docs.<profile>.json.
2. Deploy copies the files next to the schemas (/schemas/<version>/), and the version bundle is copied into the app's public/schemas/<version>/ (Versioning and publishing).
3. The editor loads the help file named in docsSchemaUrl from the same bundle, falling back to docs.<schema file> and help-texts.json. It also loads docs.type-library.json. It finds the entry for a field by its x-sidedoc id, and otherwise by path.
4. In the help panel, "More" shows the details, the schema facts and a link to the field's section in this reference: https://docs.sidedoc.app/profiles/reference/<version>/<profile>#<anchor>, where the anchor is the field id in lower case with every run of other characters than a-z and 0-9 replaced by - (ds:f00100 becomes ds-f00100).