Terms and alternative forms
A term is one entry in a glossary. This page explains what a term consists of and the rules the app applies when you save one.
What a term consists of
| Field | Required | What it is for |
|---|---|---|
| Term | Yes | The name of the term. Readers see it as the title of the term card. |
| Alternative forms: synonyms, abbreviations, variations | No | Other ways the same thing is written. Enter several values separated by a comma. |
| Definition | Yes | The explanation readers see. It is edited in a rich-text editor, so it can contain bold text, lists and links. |
| Labels | No | Tags for grouping terms. See Labels. |
A term can hold the name, alternative forms and definition in several languages. Labels belong to the term as a whole. See Languages.
What alternative forms do
The app looks for terms in page text by exact wording (see How terms are found in text). It does not know that "feature flags" is the plural of "feature flag", or that "RC" stands for "Release candidate".
Alternative forms close that gap. Add every spelling you want recognised:
- plurals and other word forms:
feature flags - abbreviations:
RC - synonyms:
feature toggle - spelling variants:
post-mortem,post mortem
When a page contains an alternative form, the reader gets the definition of the term it belongs to. Search on the glossary page also looks through alternative forms.
Each word belongs to one term
Within one glossary, a name or an alternative form can belong to only one term. Otherwise the app could not tell which definition to show.
When you save a term, the app checks this and refuses to save if:
- another term in the glossary already has this name;
- an alternative form is already used by another term, as its name or as its alternative form;
- the same alternative form is entered twice in one term;
- an alternative form is the same as the name of the term itself.
The error message lists the words that caused the conflict. The same checks apply to CSV import: a row that breaks a rule is skipped and reported, the other rows are imported.
The rule applies inside one glossary. A space glossary, the global glossary and the glossary of a linked space are checked separately, so the same word can be defined in more than one of them. In that case the reader sees every matching definition. See Space, global and linked glossaries.
Two people saving at once
Changes to one glossary are written one at a time. If two editors save at the same moment, the app waits and retries for a few seconds. Only if the glossary stays busy do you see Database writing has been blocked. Nothing is lost: save again.