SideDoc

Appearance

ADR 0005: Help texts are hand-maintained JSON files next to the schemas ​

  • Status: accepted
  • Date: 2026-10-23
  • Evidence: schemas repository commit 7ab4c73 ("track help texts in help/ with a format schema"), help/help.schema.json; monorepo commit ab62a3e (explicit docs companion resolved next to its schema)

Context ​

Each field needs help for users: a tooltip, a short line under the field, a longer text in the help panel and, on request, details. These texts are long, multilingual and edited by different people than the field structure. In the sheet they drifted: regenerating a profile could lose help text that had been backfilled by hand. Until this decision the published docs.<profile>.json files were the only copy.

Decision ​

  • Help texts live in the schemas repository as help/docs.<profile>.json, one file per profile, edited by hand.
  • The format is defined by help/help.schema.json: an x-sidedoc-help object with optional general help and fieldsById, keyed by the schema's x-sidedoc id. Text is a language map. The editor shows four levels: tooltip, short, extended and details.
  • The schemas build publishes them as docs.<profile>.json next to the profile schema. A profile can name its help file explicitly with x-sidedoc.docsSchemaUrl; the backend resolves that name in the schema's own version directory.

Consequences ​

  • Regenerating a profile from the sheet cannot overwrite help text.
  • Help files can be linted and validated against their format schema in the schemas repository.
  • Field ids are a contract between the sheet, the help files and the mapping files. Renaming an id needs changes in all three.
  • The online help pipeline is described in Online help pipeline.