Skip to main content

How to work with the glossary

When you'd do this: when you want REQQA to share a precise, agreed vocabulary across your requirements and stories — defining the terms that matter, signing them off, and keeping the cross-references current as your content changes.

The glossary is REQQA's shared dictionary of terms for your organisation. Each term carries a definition, an optional reference, see-also and synonym lists, and a signed-off / draft status. Once a term is defined, REQQA indexes every place it appears across your missions, requirements, and stories — so you can see which artefacts use a term, search for everything that mentions it, and feed consistent context into analysis and definition generation.

A well-kept glossary does three jobs: it stops the same concept being described two different ways across your requirements, it gives the analysis engine something to check definitions against (the DeFOSPAM D-D / undefined term checks), and it surfaces terms that are used but never defined so you can close the gap.

tip

Terms are stored lower-cased and matched case-insensitively. You don't need to worry about how a word is capitalised in your content — define "audit trail" once and it matches "Audit Trail", "audit trail", and "AUDIT TRAIL" wherever they appear.

Open the Dictionary Manager​

Everything starts at the Dictionary Manager (dictmanager). It's the hub page for the glossary, with a side menu that links to the four working areas:

  • Organisation Glossary — every term defined for your organisation.
  • Application Glossary — only the terms that actually appear in the current application's artefacts (the same list, filtered to your selected app).
  • Term Suggestions — terms REQQA's analysis flagged as undefined.
  • Index Search — find artefacts that use one or more glossary terms.

List and filter your terms​

Click Organisation Glossary to open the term list (dictlistterms). Each row shows the term, its status, and a count of how many artefacts it appears in (its index count). You can narrow the list two ways:

  • By status — show all terms, only signed off (verified) terms, or only draft terms still awaiting review.
  • By scope — the Application Glossary view (dictlistterms?scope=app) restricts the list to terms that are indexed in the requirements and stories of your currently selected application, with per-app appearance counts. This is the view to use when you want to know "what vocabulary does this app actually use?" If your profile has no application selected, the page falls back to the organisation-wide list.

Add a term​

From the term list, click Add Term to open the add form (dicttermadd). Fill in:

  • Term — the word or phrase. It's stored lower-cased automatically.
  • Definition — what the term means in your domain.
  • Reference — an optional source, standard, or document the definition comes from.
  • See also / Synonyms — related terms and alternative wordings.
  • Status — Draft or Signed Off. New terms default to Draft.

You don't have to write the definition yourself. Tick Generate definition with AI and leave the definition blank — when you save, REQQA generates one synchronously. It does this with real context: it reads the artefacts where the term already appears (requirements, stories, the application mission), the definitions of your other glossary terms, and your application's mission as the domain, then asks the model for a concise definition. The term is saved immediately with a placeholder, then updated in place once generation completes.

note

AI definition generation needs your organisation to have an AI provider configured. See AI models and cost for how that's set up and what it costs.

After saving, REQQA takes you to the term's view page, where you can see its definition, references, and how many artefacts currently reference it.

Edit and sign off a term​

Open a term and click Edit (dicttermedit) to revise any field. The most important edit is promoting a term from Draft to Signed Off once your team agrees the definition is correct — that's the difference between "someone typed something" and "this is the agreed meaning". The status filter on the term list lets you find everything still sitting in draft.

Review AI term suggestions​

When REQQA analyses a requirement or story and finds a term that's used but not defined, it records an undefined term issue with a suggested term and a suggested definition. The Term Suggestions page (dictsuggestions) collects these for your currently selected application: every open undefined-term issue, grouped so a term that turned up in several artefacts appears once with a count of how often it was flagged.

Work through the suggestions and, for each one worth keeping, add it to the glossary (you can carry the suggested definition straight across as your starting point, then refine and sign it off). This is the fastest way to grow a glossary that matches what your content actually talks about, rather than guessing in advance.

tip

Suggestions are scoped to the application currently selected in your profile. If the page is empty, check you have the right app selected — and that you've run analysis on its requirements or stories, since suggestions come from analysis issues.

Search the term index​

The Index Search page (termIndexSearch) answers the reverse question: which artefacts use these terms? Enter one or more terms (separated by commas), then choose:

  • Type — search all artefacts, or just requirements, stories, or missions.
  • Match — any (artefacts containing at least one of your terms) or all (only artefacts that contain every term you listed).

Results list each matching requirement, story, or mission with the terms it matched, and link straight through to the artefact. Only terms that are actually in your glossary are searched — anything you type that isn't a defined term is reported back to you as unknown, which is a useful hint that you may have a term to add.

Keep the index current — re-index after changes​

The term index is built by scanning artefact text for your defined terms. That means it can drift out of date in two situations:

  1. You add or rename a glossary term. Existing requirements and stories were indexed against the old set of terms, so a newly defined term won't show appearance counts or turn up in Index Search until the affected artefacts are re-scanned.
  2. You edit an artefact's text. REQQA re-indexes a requirement or story when you save it, so individual edits stay current automatically — but a bulk import or an external change may leave the index stale.

REQQA gives you re-index actions at three levels:

  • One requirement — the re-index control on a requirement re-scans just that record (reindexReq).
  • All requirements in the current app — re-scans every requirement for the selected application (reindexAllReqs).
  • Everything for an application — re-scans the mission, all requirements, and all stories for one app in a single pass (reindexAllForApp), reporting how many term occurrences it found in each.

Each re-index clears the old index entries for an artefact and rebuilds them against the current glossary, so after adding a batch of new terms, run the app-wide re-index to make sure appearance counts, Index Search, and the Application Glossary all reflect reality.

caution

After defining new terms, your existing requirements and stories will not show those terms until you re-index them. If a term you've just defined shows an index count of zero where you expect matches, run a re-index before assuming something is wrong.

Result​

A glossary your whole team can rely on: agreed, signed-off definitions for the terms that matter; AI suggestions turned into real entries instead of recurring analysis issues; and a term index that's current, so you can trace any term to every requirement, story, and mission that uses it — and feed that consistency back into analysis and story generation.