deepset-ai · dfokina · Dec 10, 2025 · Dec 9, 2025 · Dec 9, 2025 · Dec 9, 2025
@@ -32,9 +32,8 @@ jobs:
       - name: Vale
         uses: errata-ai/vale-action@v2
         with:
-          files: |
-            docs-website/docs
-            docs-website/versioned_docs
+          vale_flags: "--config=docs-website/.vale.ini"
+          files: docs-website/docs
           reporter: github-pr-review
           fail_on_error: false
         env:

@@ -5,3 +5,17 @@ MinAlertLevel = suggestion
 
 [*.{md,mdx}]
 BasedOnStyles = Vale, Google, MyStyle
+
+# Disable Vale's built-in spell checker (flags technical terms like "embedders")
+Vale.Spelling = NO
+
+# Disable Google.Headings - conflicts with MyStyle.Headings (title case vs sentence case)
+# and doesn't handle PascalCase component names well
+Google.Headings = NO
+
+# Disable Google.Passive - too noisy for technical documentation where passive voice
+# is often appropriate and hard to rephrase
+Google.Passive = NO
+
+# Disable Google.Acronyms - AI/ML acronyms like RAG, LLM are well-known to our audience
+Google.Acronyms = NO
@@ -9,3 +9,5 @@ action:
 swap:
   '\b(?:eg|e\.g\.)[\s,]': for example
   '\b(?:ie|i\.e\.)[\s,]': that is
+  '\betc\.': and so on
+  '\bvs\.': versus
@@ -0,0 +1,9 @@
+extends: substitution
+message: "Use '%s' instead of the abbreviation '%s'."
+level: warning
+ignorecase: true
+action:
+  name: replace
+swap:
+  '\bmisc\b': miscellaneous
+  '\bdoc\b': document
@@ -0,0 +1,7 @@
+extends: existence
+message: "Avoid 'please' in instructions—it can make actions seem optional. Use imperative instead."
+level: warning
+ignorecase: true
+scope: text
+tokens:
+  - please
@@ -1,14 +1,13 @@
 extends: existence
-message: "Prefer second person (e.g., 'you') instead of '%s'."
+message: "Prefer second person ('you') instead of '%s'."
 level: warning
-nonword: true
 scope: text
 tokens:
   - the user
   - the customer
   - the client
-  - he
-  - she
-  - his
-  - her
+  - '\bhe\b'
+  - '\bshe\b'
+  - '\bhis\b'
+  - '\bher\b'
   - their system
@@ -1,12 +1,11 @@
 extends: substitution
 message: "'%s' is not the correct branding. Use '%s' instead."
 level: error
-ignorecase: true
+ignorecase: false
 swap:
   Deepset: deepset
+  DEEPSET: deepset
   Huggingface: Hugging Face
   huggingface: Hugging Face
   HuggingFace: Hugging Face
-  Haystack: Haystack  # Pass-through to suppress errors from wrong variants
-  haystack: Haystack
-  Deepset Platform: deepset AI Platform
+  HAYSTACK: Haystack
@@ -1,5 +1,5 @@
 extends: substitution
-message: "Use uppercase for file extensions (e.g., '%s' → '%s')."
+message: "Use uppercase for file extensions: '%s' → '%s'."
 level: warning
 ignorecase: false
 swap:

@@ -0,0 +1,25 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: warning
+ignorecase: true
+action:
+  name: replace
+swap:
+  drop-down list: list
+  drop-down: list
+  dropdown: list
+  radio button: option
+  radio buttons: options
+  text field: field
+  text fields: fields
+  text area: field
+  hyperlink: link
+  hyperlinks: links
+  pop-up menu: context menu
+  popup menu: context menu
+  push button: button
+  push buttons: buttons
+  list box: list
+  choice box: list
+  pull-down list: list
+  scroll bar: scroll
@@ -1,5 +1,5 @@
 extends: capitalization
-message: "Headings and titles should use title case (e.g., 'Create a Workspace in deepset Cloud')."
+message: "Headings and titles should use title case."
 level: warning
 scope: heading
 style: AP
@@ -1,5 +1,5 @@
 extends: existence
-message: "Keyboard keys should be capitalized (e.g., 'Delete', 'F2')."
+message: "Keyboard keys should be capitalized ('Delete', 'Enter', 'F2')."
 level: warning
 scope: text
 tokens:

@@ -1,15 +1,7 @@
 extends: existence
-message: "Spell out numbers zero through nine unless part of time, measurement, or list."
-level: warning
+message: "Consider spelling out numbers zero through nine (exceptions: time, measurements, lists with larger numbers)."
+level: suggestion
 scope: text
 nonword: true
 tokens:
-  - 1
-  - 2
-  - 3
-  - 4
-  - 5
-  - 6
-  - 7
-  - 8
-  - 9
+  - '\b[1-9]\b'
@@ -1,8 +1,8 @@
 extends: existence
 message: "Wrap parameter, class, or method names like '%s' in backticks."
-level: warning
+level: suggestion
 scope: text
 raw:
-  - '\b[a-zA-Z_][a-zA-Z0-9_]*\(\)'      # Methods like pipeline()
-  - '\b[A-Z][a-zA-Z0-9]*\b'             # Class names like MyClass
+  - '\b[a-zA-Z_][a-zA-Z0-9_]*\(\)'      # Methods like pipeline(), run()
+  - '\b[a-z]+_[a-z_]+\b'                # snake_case like max_length
   - '\b[a-z]+[A-Z][a-zA-Z0-9]*\b'       # camelCase like maxDepth
@@ -0,0 +1,9 @@
+extends: substitution
+message: "Write '%s' without a hyphen: '%s'."
+level: warning
+ignorecase: true
+action:
+  name: replace
+swap:
+  question-answering: question answering
+  document-retrieval: document retrieval
@@ -0,0 +1,8 @@
+extends: existence
+message: "Avoid '%s'—it's implied by the colon. Rephrase or remove."
+level: suggestion
+ignorecase: true
+scope: text
+tokens:
+  - the following
+  - as follows
@@ -8,3 +8,7 @@ tokens:
   - simply
   - basically
   - leverage
+  - very
+  - really
+  - extremely
+  - quite
@@ -0,0 +1,24 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: warning
+ignorecase: true
+action:
+  name: replace
+swap:
+  utilize: use
+  utilizes: uses
+  utilizing: using
+  utilized: used
+  purchase: buy
+  purchases: buys
+  purchasing: buying
+  purchased: bought
+  assist: help
+  assists: helps
+  assisting: helping
+  assisted: helped
+  info: information
+  leverage: use
+  leverages: uses
+  leveraging: using
+  leveraged: used