When Workspace Means Two Different Things in the Same Company

In product documentation, a workspace is where a team collaborates. In infrastructure documentation, a workspace might be an isolated deployment environment.

Both definitions can be useful. Trouble starts when a glossary treats them as a single global meaning, or when an assistant retrieves one definition and uses it in the other context.

Org Lexicon is a small experiment in making definitions reviewable, scoped, and traceable to their sources. Its most consequential operation is the human approval step between finding a definition and treating it as agreed vocabulary.

Extract a candidate without approving it

The bundled product fixture contains explicit definitions:

**Workspace**: A named area where product teams collaborate.
**Account** means the billing identity for a customer.

The infrastructure fixture gives Workspace its own definition. Extraction takes a scope, so the two meanings can remain separate rather than overwriting one another.

Use Python 3.11 or newer, with no third-party runtime dependencies:

git clone https://github.com/asadani/org-lexicon.git
cd org-lexicon
out_dir="$(mktemp -d)"

python -m org_lexicon extract --root fixtures --scope product \
  --file product.md --out "$out_dir/product-candidates.json"

python -m org_lexicon extract --root fixtures --scope infrastructure \
  --file infrastructure.md --out "$out_dir/infrastructure-candidates.json"

Open the two JSON files. The extracted definitions are candidates with source evidence. They have not become approved entries merely because a parser recognized their syntax.

The current parser intentionally recognizes a narrow set of full-line definition forms outside fenced code. It does not infer every term that an organization uses or discover the correct meaning from arbitrary prose.

Give approval an explicit role

A reviewer can inspect a candidate and approve it into a glossary with a reviewer label and date. This makes the transition visible: a document contained a definition, and someone accepted it for a particular scope.

The approved glossary can also retain discouraged aliases. In the example workflow, team space becomes a discouraged spelling for the product term Workspace. A usage check can then locate that phrase in a selected guide and suggest the canonical term.

That alias is a vocabulary decision. It is not an inferred statement that every occurrence of two phrases means the same thing. The checker uses bounded text matching, so team spacesuit should not become a false match for team space.

Ask for definitions where the document needs them

A guide can mark a reference explicitly:

Ask about [[term:external collaborator]] and [[term:workspace]].

The shipped guide contains an undefined marked term as well as the discouraged alias. Those are actionable review findings: supply or approve the missing definition, and check whether the old name should be replaced.

The tool does not flag every unfamiliar word. Explicit markers let the author choose which concepts require agreement, at the cost of maintaining the annotations.

The README walkthrough shows the full approval, export, and usage-check sequence against the fixtures.

A changed source deserves another review

An approved term retains a fingerprint of its source. If the source file changes or disappears, a check reports that condition. It does not silently refresh the fingerprint or infer that the definition remains valid.

Whole-file fingerprints are conservative: an unrelated edit can ask for review. They also do not establish that the reviewer approved a correct definition. They preserve a relationship to a particular version of the source.

Start with the terms that change decisions

A useful first glossary is small. Choose terms whose meaning changes an implementation or a user action, rather than extracting the largest possible vocabulary.

Try a product scope and an infrastructure scope with one overlapping word. Ask whether a reviewer can explain which meaning applies and find its source. Then check a guide that uses an old alias. Record useful findings and the effort needed to maintain the glossary.

The MIT-licensed repository provides candidate extraction, reviewed glossaries, exports, and scoped checks. The design question is whether approval, scope, and provenance make the vocabulary easier to use than an ordinary word list.

AI disclosure: This article was drafted with AI assistance using the project documentation and fixtures. The organization and terminology examples are illustrative.