Help file format

Format of the hand-maintained help files (help/docs.<profile>.json). Each file holds the online help for one profile, keyed by the schema's x-sidedoc field id. The build publishes them as docs.<profile>.json next to the profile schema. The editor shows four levels: tooltip (hover), short (under the field), extended (help panel) and details (help panel, opened on request).

Source: help/help.schema.json in the schemas repository. scripts/lint_help.py validates every help file against it. How to write good help: see Writing help texts.

File

{
  "$schema": "./help.schema.json",
  "title": "Datasheet help",
  "x-sidedoc-help": {
    "general": {
      "title": {
        "en": "..."
      },
      "short": {
        "en": "..."
      },
      "extended": {
        "en": "..."
      }
    },
    "fieldsById": {
      "ds:f00100": {
        "label": "Title",
        "path": "title",
        "tooltip": {
          "en": "..."
        },
        "short": {
          "en": "..."
        },
        "extended": {
          "en": "..."
        },
        "details": {
          "examples": [
            {
              "value": "..."
            }
          ],
          "notes": {
            "en": "..."
          },
          "seeAlso": [
            {
              "url": "https://...",
              "label": {
                "en": "..."
              }
            }
          ]
        }
      }
    }
  }
}

Top level

Key	Value	Meaning
$schema	string
$id	string	Published URL of this help file.
title	string
description	string
x-sidedoc-help (required)	object

x-sidedoc-help

Key	Value	Meaning
general	object	Help shown when no field is selected.
fieldsById (required)	object	Help per field, keyed by x-sidedoc id (for example ds:f00100).

general holds title, short and extended, each a LangMap.

LangMap

Text per language. Keys are the editor languages; an empty string means not written yet. The editor falls back to English.

Keys: en, nl, fr, de. Values: text.

FieldHelp

Key	Value	Meaning
label	string	Field label, copied from the schema by the build. Do not edit: change the schema instead.
path	string	Dotted property path in the document, copied from the schema by the build. Do not edit.
tooltip	LangMap	Level 1. One line shown on hover or focus of the (?) icon. No full stop needed.
short	LangMap	Level 2. What to fill in, shown under the field. One or two sentences.
extended	LangMap	Level 3. Why the field matters and how to fill it in well. Shown in the help panel. Must add something to the short text, not repeat it.
details	Details

Details

Level 4. Shown in the help panel under 'More', closed by default. Examples, notes and links. Facts that follow from the schema (cardinality, vocabulary, format, mappings) are added by the editor and the docs generator; do not write them here.

Key	Value	Meaning
examples	array of Example
notes	LangMap	Extra guidance: edge cases, common mistakes, conventions. Plain text; blank lines separate paragraphs.
seeAlso	array of Link
mapping	array of objects	Generated by the build from rdf-targets/. Do not edit.

Example

Key	Value	Meaning
value (required)	string or number or boolean or object or array	The example value as a user would type it. A string, or a JSON value for structured fields.
lang	string	Show this example only in this editor language. Omit for language-neutral examples.
quality	one of good, bad	Mark counter-examples as bad; the editor labels them 'Avoid'.
note	LangMap	Why this is a good (or bad) example.

Link

Key	Value	Meaning
url (required)	string
label	LangMap
note	LangMap	One line on what the link is, for example which version.