From eb4e8834603a6d001dd679ba930153ab61397943 Mon Sep 17 00:00:00 2001 From: Dan Finn Date: Tue, 3 Feb 2026 09:04:41 -0500 Subject: [PATCH] feat: align Vale rules with updated style guide Update existing rules and add new rules to match the latest DigitalOcean style guide changes from product-docs. Updated rules: - ConsiderateWriting: add violent metaphors and idioms - GenderBias: add hyphenated variants - DigitalOceanTerms: add AI product terminology New rules: - EmDashes: flag en/em dashes - ExclamationMarks: warn about exclamation marks - RangeSpacing: flag spaces in ranges - ModalAuxiliaries: warn about modal verbs - VagueLinkText: flag vague link text - WordChoicePhrasalVerbs: enforce phrasal verb usage - Ellipses: warn about inappropriate ellipses - LeadingZero: require leading zero in decimals Total rules: 29 (was 21) --- styles/DigitalOcean/ConsiderateWriting.yml | 13 +++++++++++-- styles/DigitalOcean/DigitalOceanTerms.yml | 4 ++++ styles/DigitalOcean/Ellipses.yml | 12 ++++++++++++ styles/DigitalOcean/EmDashes.yml | 8 ++++++++ styles/DigitalOcean/ExclamationMarks.yml | 8 ++++++++ styles/DigitalOcean/GenderBias.yml | 2 ++ styles/DigitalOcean/LeadingZero.yml | 7 +++++++ styles/DigitalOcean/ModalAuxiliaries.yml | 16 ++++++++++++++++ styles/DigitalOcean/RangeSpacing.yml | 9 +++++++++ styles/DigitalOcean/VagueLinkText.yml | 16 ++++++++++++++++ styles/DigitalOcean/WordChoicePhrasalVerbs.yml | 11 +++++++++++ 11 files changed, 104 insertions(+), 2 deletions(-) create mode 100644 styles/DigitalOcean/Ellipses.yml create mode 100644 styles/DigitalOcean/EmDashes.yml create mode 100644 styles/DigitalOcean/ExclamationMarks.yml create mode 100644 styles/DigitalOcean/LeadingZero.yml create mode 100644 styles/DigitalOcean/ModalAuxiliaries.yml create mode 100644 styles/DigitalOcean/RangeSpacing.yml create mode 100644 styles/DigitalOcean/VagueLinkText.yml create mode 100644 styles/DigitalOcean/WordChoicePhrasalVerbs.yml diff --git a/styles/DigitalOcean/ConsiderateWriting.yml b/styles/DigitalOcean/ConsiderateWriting.yml index 643e089..4294429 100644 --- a/styles/DigitalOcean/ConsiderateWriting.yml +++ b/styles/DigitalOcean/ConsiderateWriting.yml @@ -12,6 +12,15 @@ swap: insanely: incredibly dummy: placeholder|stand-in|test stupid: foolish|ludicrous|unintelligent - (?:fall|fell|falling) on deaf ears: missed the mark|was ignored + (?:fall|fell|falling) on deaf ears: missed the mark|was ignored|were ignored blind spot: weakness|something we overlooked - sanity check: check + sanity check: check|verify|review + kill (?:a|the) (?:process|task|job): terminate|stop + killed (?:a|the) (?:process|task|job): terminated|stopped + killing (?:a|the) (?:process|task|job): terminating|stopping + shoot (?:an|the|a) (?:email|message): send|forward|submit + shot (?:an|the|a) (?:email|message): sent|forwarded|submitted + shooting (?:an|the|a) (?:email|message): sending|forwarding|submitting + tribal knowledge: existing knowledge|internal documentation + low-hanging fruit: early opportunity|simple task + white knight: system recovery diff --git a/styles/DigitalOcean/DigitalOceanTerms.yml b/styles/DigitalOcean/DigitalOceanTerms.yml index 2ab9e3b..4a8485d 100644 --- a/styles/DigitalOcean/DigitalOceanTerms.yml +++ b/styles/DigitalOcean/DigitalOceanTerms.yml @@ -21,3 +21,7 @@ swap: 'Digitalocean': DigitalOcean 'digitalocean^(?:.com)': DigitalOcean droplet[s]?: Droplet(s) + \bspace[s]?(?! bucket| for| between| after| before| around| in): Space(s) + the Gradient AI Platform: Gradient AI Platform + model [Pp]layground: Model Playground + agent [Pp]layground: Agent Playground diff --git a/styles/DigitalOcean/Ellipses.yml b/styles/DigitalOcean/Ellipses.yml new file mode 100644 index 0000000..64a4ba0 --- /dev/null +++ b/styles/DigitalOcean/Ellipses.yml @@ -0,0 +1,12 @@ +extends: existence +message: "Use ellipses only to represent truncated output or omitted quoted text, not for tone or style: '%s'." +link: https://docs.digitalocean.com/style/digitalocean/grammar/punctuation +level: warning +scope: sentence +nonword: true +# This rule flags ellipses in narrative text (not code blocks) +# It will produce some false positives in legitimate technical uses +# Use Vale comments to ignore specific instances if needed +tokens: + - '\.\.\.' + - '…' # Unicode ellipsis character diff --git a/styles/DigitalOcean/EmDashes.yml b/styles/DigitalOcean/EmDashes.yml new file mode 100644 index 0000000..421e834 --- /dev/null +++ b/styles/DigitalOcean/EmDashes.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Do not use en dashes (–) or em dashes (—). Use hyphens (-) for ranges and compound modifiers." +link: https://docs.digitalocean.com/style/digitalocean/grammar/punctuation +level: error +nonword: true +tokens: + - '–' # en dash (U+2013) + - '—' # em dash (U+2014) diff --git a/styles/DigitalOcean/ExclamationMarks.yml b/styles/DigitalOcean/ExclamationMarks.yml new file mode 100644 index 0000000..2f0d86d --- /dev/null +++ b/styles/DigitalOcean/ExclamationMarks.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Avoid exclamation marks in technical documentation. Rewrite for clarity instead of relying on punctuation for emphasis." +link: https://docs.digitalocean.com/style/digitalocean/grammar/punctuation +level: warning +nonword: true +scope: sentence +tokens: + - '!' diff --git a/styles/DigitalOcean/GenderBias.yml b/styles/DigitalOcean/GenderBias.yml index 751e9ff..db1d779 100644 --- a/styles/DigitalOcean/GenderBias.yml +++ b/styles/DigitalOcean/GenderBias.yml @@ -21,4 +21,6 @@ swap: sales(?:m[ae]n|wom[ae]n): salesperson or sales people work(?:m[ae]n|wom[ae]n): worker(s) manhours: workhours + man-hours: work-hours manpower: staff + work(?:m[ae]n|wom[ae]n): worker(s) diff --git a/styles/DigitalOcean/LeadingZero.yml b/styles/DigitalOcean/LeadingZero.yml new file mode 100644 index 0000000..acf58f7 --- /dev/null +++ b/styles/DigitalOcean/LeadingZero.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Include a leading zero for decimals less than one: '%s'." +link: https://docs.digitalocean.com/style/digitalocean/grammar/numbers +level: error +nonword: true +tokens: + - '(?:^|\s)\.(\d+)' # Decimal without leading zero like " .5" diff --git a/styles/DigitalOcean/ModalAuxiliaries.yml b/styles/DigitalOcean/ModalAuxiliaries.yml new file mode 100644 index 0000000..eec8acd --- /dev/null +++ b/styles/DigitalOcean/ModalAuxiliaries.yml @@ -0,0 +1,16 @@ +extends: existence +message: "Avoid modal auxiliaries like '%s', which can confuse non-native speakers. Use direct, present-tense verbs instead." +link: https://docs.digitalocean.com/style/digitalocean/language/verbs +level: warning +ignorecase: true +tokens: + - '\bshould\b' + - '\bcould\b' + - '\bmay\b' + - '\bmight\b' + - '\bshould not\b' + - '\bcould not\b' + - '\bmay not\b' + - '\bmight not\b' + - '\bshouldn''t\b' + - '\bcouldn''t\b' diff --git a/styles/DigitalOcean/RangeSpacing.yml b/styles/DigitalOcean/RangeSpacing.yml new file mode 100644 index 0000000..612fbeb --- /dev/null +++ b/styles/DigitalOcean/RangeSpacing.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Do not add spaces around hyphens in ranges: '%s'." +link: https://docs.digitalocean.com/style/digitalocean/grammar/hyphens +level: error +nonword: true +tokens: + - '\d+\s+-\s+\d+' # numeric ranges like "10 - 20" + - '\d+\s+-\d+' # "10 -20" + - '\d+-\s+\d+' # "10- 20" diff --git a/styles/DigitalOcean/VagueLinkText.yml b/styles/DigitalOcean/VagueLinkText.yml new file mode 100644 index 0000000..4a229a5 --- /dev/null +++ b/styles/DigitalOcean/VagueLinkText.yml @@ -0,0 +1,16 @@ +extends: existence +message: "Use descriptive link text. Avoid vague phrases like '%s'." +link: https://docs.digitalocean.com/style/digitalocean/language/links-and-link-text +level: error +ignorecase: true +tokens: + - 'click here' + - 'learn more' + - 'read more' + - 'more info' + - 'more information' + - 'this page' + - 'this link' + - 'here' + - 'click this link' + - 'follow this link' diff --git a/styles/DigitalOcean/WordChoicePhrasalVerbs.yml b/styles/DigitalOcean/WordChoicePhrasalVerbs.yml new file mode 100644 index 0000000..efb5ef0 --- /dev/null +++ b/styles/DigitalOcean/WordChoicePhrasalVerbs.yml @@ -0,0 +1,11 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +link: https://docs.digitalocean.com/style/digitalocean/language/word-choice +ignorecase: true +level: error +action: + name: replace +swap: + log into: log in to + logged into: logged in to + logging into: logging in to