Skip to content

Comments

Use Vale Vocabularies#63

Merged
theletterf merged 2 commits intomainfrom
add-vocab
Dec 5, 2025
Merged

Use Vale Vocabularies#63
theletterf merged 2 commits intomainfrom
add-vocab

Conversation

@colleenmcginnis
Copy link

@colleenmcginnis colleenmcginnis commented Dec 3, 2025

Fixes #61

Adds two Vale Vocabularies containing Elastic product/feature names and third-party product names. This will likely be easier to manage exact product/feature names without having to add them as exceptions in individual styles.

Process

  • I started with the list of exceptions in styles/Elastic/Capitalization.yml and sorted them into ElasticTerms (Elastic-specific products and features) vs. ThirdPartyProducts (non-Elastic products). I created two separate vocabulary files in case we ever want to sync this list of Elastic product names with others (like in docs-builder and the VS Code extension).
  • Then I added all the product names from docs-builder's product list to ElasticTerms and deduplicated as needed.
  • In ElasticTerms, for product and feature names that could also be used as a regular word (for example, Agent, Analytics, Machine Learning), I prefixed the strings with (?i) to mark the entire pattern as case-insensitive. This will allow us to use either the title case version when referring to the specific product/feature and the lower case version when using it as a regular word.
  • Then I added a list of third-party products from a previous linting attempt to ThirdPartyProducts and deduplicated as needed.
  • In ThirdPartyProducts, there are a several official product names that start with a lower case character. To account for when those product names are used at the beginning of the sentence, I prefixed the strings with (?i) to mark the entire pattern as case-insensitive. (This decision is definitely up for debate.)

Potential follow up tasks

  • Update the contributing docs prompting contributors to add to these lists instead of individual style exceptions where appropriate.
  • Consider adding an IndustryTerms list for additional items like GeoJSON and QoS.
  • In the long term consider syncing Elastic product list names across tools (docs-builder, VS Code extension).

@colleenmcginnis colleenmcginnis self-assigned this Dec 3, 2025
@colleenmcginnis colleenmcginnis changed the title [work in progress] Use Vale Vocabularies Use Vale Vocabularies Dec 4, 2025
@colleenmcginnis colleenmcginnis marked this pull request as ready for review December 4, 2025 22:30
@theletterf
Copy link
Collaborator

This is excellent, thank you! I think the (?i) solution is brilliant as long as it doesn't interfere with rules where we want to preserve capitalization of proper nouns / product names in a certain way (which I think is not the case with the current PR). I'm merging this one :)

As for the next actions, I'm adding the recommendation about editing the Vocabulares in the PR I'm preparing for the public docs. For docs-builder integration, you might want to have a look at this one: elastic/docs-builder#1988

@theletterf theletterf merged commit c4bcc7e into main Dec 5, 2025
1 check passed
@colleenmcginnis colleenmcginnis deleted the add-vocab branch December 8, 2025 15:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Consider using Vale Vocabularies

2 participants