Skip to main content

The Glossary

Every project develops its own vocabulary. The same word can mean different things to different people, and a requirement that reads cleanly to its author can be ambiguous to a reviewer who reads "session", "account", or "claim" differently. REQQA's glossary — sometimes called the dictionary — is where an organisation pins down that shared vocabulary, so that requirements, stories and analysis all draw on the same definitions.

The glossary is more than a list of words. It is wired into two parts of REQQA that you see elsewhere in the product: the analysis engine flags undefined terms it encounters, and the application content you read in the browser quietly links recognised terms back to their definitions. This page explains the model underneath all of that.

What a glossary entry is​

Each glossary entry is one row in the definitions table, scoped — like everything in REQQA — to an organisation. An entry carries:

  • Term — the word or phrase being defined. Terms are stored in lower case so that matching is case-insensitive everywhere.
  • Definition — the explanatory text. A new entry that has not yet been written reads To be defined until someone (or the AI) fills it in.
  • Verified — a draft/signed-off flag. Stored internally as 'T' or 'F', it is shown in the UI as Draft versus Signed Off. A verified term is one the business has agreed on; a draft is still provisional.
  • Synonyms — alternative words that mean the same thing, recorded so readers can find the canonical term.
  • See also — related terms worth cross-referencing.
  • Source or reference — where the definition came from (a standard, a contract, a policy).
note

Verifying a term is a deliberate act. AI-generated definitions and freshly added entries start as drafts. Treat Signed Off as a statement that the organisation has reviewed and accepts the wording — it is the difference between "someone typed this" and "we agree this is what the word means".

The Dictionary Manager​

The Dictionary Manager is the home of the glossary. From it you reach four areas:

  • Organisation Glossary — every term defined for your organisation.
  • Application Glossary — the same list filtered to terms that actually appear in your current application's requirements and stories.
  • Term Suggestions — terms the analysis engine has proposed but you have not yet defined.
  • Index Search — a tool for finding which artefacts use which terms.

The organisation-wide list is the master vocabulary. The application-scoped view does not hold its own separate terms; it shows the organisation terms that have been seen in that application's content, derived from the term index described below. This is why a term can exist in your organisation glossary yet not appear under a particular application — nothing in that application has used it yet.

The term index​

The glossary would be inert if REQQA didn't know where each term is used. That is the job of the term index (the termindex table): a cross-reference recording, for each defined term, which requirements, stories and application missions mention it.

Indexing is pure string matching — no AI is involved. When an artefact is re-indexed, REQQA clears that artefact's existing index rows, scans its text fields against the list of defined terms, and writes a fresh row for every term it finds. Each row records the term, the artefact type (requirement, story or mission) and the artefact's id.

Because the index is just matched text, it goes stale the moment either side changes:

  • If you add or rename a glossary term, existing artefacts that use that word are not retroactively indexed until they are re-indexed.
  • If you edit a requirement or story, its index entries reflect the old text until it is re-indexed.
caution

The index is a snapshot, not a live query. After a round of glossary editing or content changes, expect to re-index so that Index Search, the application glossary view, and the usage counts shown against each term are accurate again. Re-indexing is cheap — it is string matching, not an AI call — so run it freely.

Index Search turns the index around: instead of asking "where is this term used?", you give it one or more terms and it returns the requirements, stories and missions that contain them. You can restrict the artefact type, and choose whether a match means any of your terms (OR) or all of them (AND). Only terms that are actually in the glossary are searched — if you type a word that isn't defined, Index Search tells you it is unknown rather than silently returning nothing.

This is how you answer questions like "which requirements talk about both consent and retention?" — useful when a definition changes and you need to find everything it touches.

Term suggestions​

You do not have to discover your own vocabulary by hand. When the analysis engine runs the DeFOSPAM D (Definition) checks over a story or requirement, it raises an undefined_term issue for each significant word it cannot find in the glossary, often with a proposed definition attached.

The Term Suggestions page gathers these for your current application: every open undefined-term issue, grouped by the suggested term, with a count of how many artefacts raised it. A term mentioned across many stories with no definition is a strong candidate to define first. You can accept a suggestion to create a real glossary entry, then refine its wording.

AI-generated definitions​

When you add a term, you can ask REQQA to draft the definition for you rather than typing it. The AI does not write in a vacuum — it is given context drawn from your own project: up to a few artefacts that already use the term (their titles and content), a sample of your existing glossary so the new definition stays consistent in tone and depth, and your application's mission as the domain backdrop. The result is saved as a draft for you to review and sign off. As with all AI features, the call is logged against your organisation's usage. See AI models and cost for how that is configured and metered.

Auto-linking in application content​

Once terms are defined, REQQA makes them visible wherever you read content in the app. Requirement and story content rendered in the browser is glossary-aware: as the page loads, REQQA fetches your organisation's terms and wraps every recognised term in the text with a subtle highlight. Hover over a highlighted term and a tooltip shows its definition (truncated for the tooltip — the full definition lives on the term's own page).

A few details worth knowing about how this behaves:

  • Matching is case-insensitive and respects word boundaries, so plan will not light up inside planet.
  • Longer phrases win over their parts — access control is wrapped as one term rather than matching access and control separately.
  • It never reaches inside code, pre-formatted blocks, or text that is already a glossary term, so highlighting can't nest or corrupt formatting.

This is the everyday payoff of maintaining the glossary: definitions surface exactly where a reader needs them, without anyone having to look anything up.

The published help-site Glossary​

The glossary you maintain inside REQQA is also the source of the public Glossary on this help site. That reference page is generated, not written by hand — a build step reads the definitions table and produces the markdown fresh at each release. Editing a definition in the app is therefore the only way to change the published glossary; the next release picks it up.

The generated page is scoped to the terms that appear in REQQA's own application content (via the term index), listed alphabetically with a letter-grouped index at the top. Within each definition, any mention of another defined term is turned into a cross-reference link, and verified terms are marked as such. A live filter box lets readers narrow the list as they type.

note

A handful of generation rules exist purely to keep the markdown safe: term anchors are prefixed (so a term starting with a digit still produces a valid link), angle brackets in definitions are escaped (so text like <value> renders as written rather than being read as markup), and terms beginning with a symbol are grouped under "Symbols". These are behind-the-scenes details — what you maintain in the app is what you get on the page.