Skip to content

Glossary at /docs/iac/concepts/glossary/ is not discoverable; add guidance for referencing and maintaining glossary terms #17347

@CamSoper

Description

@CamSoper

Problem description

The glossary found at /docs/iac/concepts/glossary/ is not linked from anywhere else in the documentation site, making it difficult for users to discover. There is also no documented process or guidance to ensure that:

  • The glossary is referenced from an appropriate location (e.g., main navigation, prominent docs landing page, etc.)
  • Contributors know to add new terms to the glossary when relevant content or new concepts are added elsewhere in the docs.

Suggestions for a fix

  • Identify the most logical and prominent location in the docs site (such as the top-level navigation, docs landing page, or concepts index) and add a discoverable link to the glossary.
  • Add a directive to .claude/commands/docs-review.md, or STYLE-GUIDE.md if more appropriate, instructing contributors to add new terms to the glossary when introducing new concepts/terms to the documentation.
    • Include this guidance in pull request reviews for documentation.
  • Verify all relevant locations are updated and ensure ongoing discoverability and maintainability of the glossary.

For more about review expectations, see the docs-review command and/or style guide.

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions