Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs: add a glossary to the reference section - #27165

Merged
nickvigilante merged 4 commits into
mainfrom
vigilante/docs-75-migrate-and-expand-the-notion-glossary-into-the-docs-site
Aug 3, 2026
Merged

docs: add a glossary to the reference section#27165
nickvigilante merged 4 commits into
mainfrom
vigilante/docs-75-migrate-and-expand-the-notion-glossary-into-the-docs-site

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Jul 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Adds a reference glossary at docs/reference/glossary.md that defines the Coder-specific terms and product names readers encounter across the docs, and registers it in docs/manifest.json under Reference.

The page prioritizes the term collisions around "agent": it disambiguates Coder Agents (the AI product), the workspace agent (the in-workspace daemon), and the coder_agent Terraform resource with an [!IMPORTANT] callout and cross-referenced entries. Every definition was checked against the current docs, and every internal link is a relative path that resolves in-repo.

Decision log and verification notes

Scope of this PR

  • Creates the glossary page (docs/reference/glossary.md) and its manifest entry.
  • Adds glossary drift-prevention guidance in response to review feedback (see Follow-up from review below).
  • Out of scope (tracked separately): Glossary: cross-link callouts across the docs IA, the search-ranking boost, the workspace-daemon rename decision, and the automated glossary lint guard (DOCS-604).

Follow-up from review (@bpmct)

Ben flagged the risk that terms get introduced, renamed, or deprecated without the glossary keeping up. Addressed in commit c12dea4 by pointing both humans and tooling at the glossary:

  • docs/.style/content-guidelines.md: a canonical Structural rule to update the glossary in the same change that introduces, renames, or deprecates a product or feature name.
  • .claude/skills/doc-check/SKILL.md: doc-check flags terminology changes that need a glossary update.
  • .claude/skills/write-docs/SKILL.md: authoring updates the glossary in the same change, plus a pre-handoff checklist item.
  • docs/.style/style-guide/word-choice.md: cross-links the glossary as the fuller product-name registry.

The single source of truth is the content-guidelines rule; the skills reference it rather than restate it. The automated lint guard is deliberately split into DOCS-604: it touches CI/build config and depends on the planned Coder.ProductTerms Vale rule, so keeping it out holds this PR to a doc-only footprint. The four files above are Markdown-only additions, validated in CI (markdownlint, emdash, Vale advisory) rather than re-run locally.

Source

  • Migrated and expanded from a generated glossary draft, then reconciled against the live docs.

Corrections made vs. the draft

  • AI Gateway and Agent Firewall are gated by the AI Governance Add-On (Coder v2.32+), not plain Premium. Confirmed in docs/ai-coder/ai-governance.md.
  • Coder Tasks is framed as deprecated (12-month ESR, removed from new releases starting v2.37; Coder Agents is the long-term replacement), per docs/ai-coder/tasks.md.
  • "Formerly AI Bridge" and "formerly Agent Boundaries" confirmed via the rebranding-migration and agent-firewall pages; Agent Firewall backends are nsjail (default) and landjail.
  • OpenTofu is described as a custom Terraform binary that works but is not officially supported, per docs/admin/integrations/opentofu.md.
  • Premium markers were taken from docs/manifest.json ("state": ["premium"]).

Local validation (glossary page)

  • markdownlint-cli2: 0 errors.
  • scripts/check_emdash.sh: clean.
  • Vale (Coder package): 0 errors, 0 warnings, 0 suggestions.
  • All 120 links checked; every relative link resolves in-repo.
  • 103 terms; no duplicate sibling headings (MD024 siblings_only).

Reviewer note

  • This is a first-pass migration. Per the docs authoring skill, each entry deserves a final accuracy pass before the page leaves draft. Flag any term you want reworded, split, merged, or dropped.

This PR was created with AI assistance (Coder Agents).

@nickvigilante
docs: add a glossary to the reference section
6adb7e4 
Add a reference glossary that defines Coder-specific terms and product names, including the coder_agent / workspace agent / Coder Agents disambiguation, with links to the relevant docs.
@linear-code

linear-code Bot commented Jul 10, 2026

Copy link
Copy Markdown

DOCS-75

@github-actions

github-actions Bot commented Jul 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

@nickvigilante
docs: sort the glossary terms alphabetically
f9f24a2 
Reorganize the glossary from category sections into A-Z sections, one H2 per letter with terms as H3s. Letters with no terms are omitted. Definitions, links, and the agent disambiguation callout are unchanged.
@nickvigilante
docs: disambiguate the two sub-agent glossary terms
c42a132 
Normalize both entries to the hyphenated "sub-agent" spelling used elsewhere in the docs, split them into "Sub-agent (Coder Agents)" and "Sub-agent (dev containers)", add mutual "Not to be confused with" cross-references, and note that the dev container sub-agent is a Coder term, not part of the Development Container Specification.
@nickvigilante
nickvigilante marked this pull request as ready for review July 13, 2026 14:26
@nickvigilante
nickvigilante requested a review from bpmct July 13, 2026 14:26
bpmct
bpmct reviewed Jul 23, 2026
View reviewed changes

@bpmct bpmct left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Happy this is here! Of course, my fear with this is that we introduce, update, or deprecate terms and do not update the glossary.

I suggest, as part of this PR, we update our docs style guide, and/or skills so that users and AI is comfortable with if/when/how to detect drift in the glossary.

@nickvigilante

nickvigilante commented Jul 23, 2026

Copy link
Copy Markdown
Contributor Author

Happy this is here! Of course, my fear with this is that we introduce, update, or deprecate terms and do not update the glossary.

I suggest, as part of this PR, we update our docs style guide, and/or skills so that users and AI is comfortable with if/when/how to detect drift in the glossary.

I'll happily add this. Stay tuned!

@nickvigilante
docs: add glossary drift guidance (content guidelines + skills)
c12dea4 
Address review feedback from @bpmct on #27165: document if/when/how to keep
docs/reference/glossary.md current so it does not drift as product terms are
introduced, renamed, or deprecated.

- content-guidelines.md: add a Structural rule (canonical)
- doc-check skill: flag terminology changes that need a glossary update
- write-docs skill: update the glossary in the same change; checklist item
- word-choice.md: cross-link the glossary as the fuller name registry

The automated lint guard is tracked separately (DOCS-604).
@nickvigilante
nickvigilante requested a review from a team as a code owner July 23, 2026 21:15
@nickvigilante

nickvigilante commented Jul 23, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @bpmct. Addressed in c12dea4 by teaching both the humans and the tooling where the glossary fits:

  • Canonical rule in docs/.style/content-guidelines.md (Structural rules): when a change introduces, renames, or deprecates a Coder product or feature name, update docs/reference/glossary.md in the same PR (new entry / rename with a "previously named" note / deprecation naming the replacement). It also defines what earns an entry, so the page doesn't over- or under-populate.
  • doc-check skill: flags terminology changes whose glossary entry is missing, at review time.
  • write-docs skill: authors update the glossary in the same change, with a pre-handoff checklist item.
  • word-choice.md: cross-links the glossary as the fuller product-name registry, tied to the planned Coder.ProductTerms Vale rule.

The content-guidelines rule is the single source of truth; the skills point at it rather than restate it, so it can't drift.

For the automated guard your comment hints at, I split that into a separate follow-up (DOCS-604) rather than bundle it here: a real "term used but missing from the glossary" check touches CI config and depends on the not-yet-built Coder.ProductTerms rule, so it deserves its own PR and keeps this one doc-only. Happy to pull it in here instead if you'd prefer.

@nickvigilante
nickvigilante requested a review from bpmct July 23, 2026 21:20
@github-actions github-actions Bot added the stale This issue is like stale bread. label Jul 31, 2026
@github-actions github-actions Bot closed this Aug 3, 2026
@nickvigilante nickvigilante reopened this Aug 3, 2026
@nickvigilante
nickvigilante merged commit ee7e7ec into main Aug 3, 2026
63 checks passed
@nickvigilante
nickvigilante deleted the vigilante/docs-75-migrate-and-expand-the-notion-glossary-into-the-docs-site branch August 3, 2026 18:32
@github-actions github-actions Bot locked and limited conversation to collaborators Aug 3, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

@bpmct bpmct bpmct approved these changes

Assignees

@nickvigilante nickvigilante

Labels

stale This issue is like stale bread.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@nickvigilante @bpmct