Repository: redpanda-data/docs
Pull request #1023: Redpanda Style Guide
Author: login: bllchmbrs
Created: 2025-03-21T05:24:42Z | Merged: 2025-03-21T18:13:58Z

## Description

Resolves discussion from earlier today about customizing further the Hyperlint Reviewing Capabilities.

## Page previews

No content edited.

## Checks

- [ ] New feature
- [ ] Content gap
- [ ] Support Follow-up
- [ ] Small fix (typos, links, copyedits, etc)



Diff:
diff --git a/.gitignore b/.gitignore
index 5322edac20..6560ae2362 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,3 +9,4 @@ poc-docs/
 docs/
 .docusaurus
 testResults*.json
+.hyperlint/reviewer/vale-style-guide/styles/Google/
\ No newline at end of file
diff --git a/.hyperlint/config.yaml b/.hyperlint/config.yaml
index b6664ca7e5..635ce72d06 100644
--- a/.hyperlint/config.yaml
+++ b/.hyperlint/config.yaml
@@ -1,4 +1,9 @@
 content_dir: "/modules"
-custom_style_guide:
-  enabled: true
-  path_to_style_guide_dir: "./.hyperlint/style-guide/"
+reviewer:
+  custom_style_guide:
+    enabled: true
+    path_to_style_guide_dir: .hyperlint/reviewer/custom-style-guide
+  vale_style_guide:
+    check_status_upon_review_failure: failure
+    enabled: true
+    path_to_vale_ini_file: .hyperlint/reviewer/vale-style-guide/.vale.ini
diff --git a/.hyperlint/reviewer/custom-style-guide/code-formatting.adoc b/.hyperlint/reviewer/custom-style-guide/code-formatting.adoc
new file mode 100644
index 0000000000..34ce3db42b
--- /dev/null
+++ b/.hyperlint/reviewer/custom-style-guide/code-formatting.adoc
@@ -0,0 +1,15 @@
+= Redpanda Data Documentation Code Formatting Guidelines
+
+=== Commands and code
+
+Don’t start a sentence with a command or code. Instead, try to move the code into the middle of the sentence. Introduce the command with the more descriptive word “run” instead of “use the X command".
++
+*Correct:* Run the `rpk topic create` command to create a new topic.
++
+*Incorrect:* `rpk topic create` creates a new topic.
+
+Similarly, do not start a sentence with a filename.
++
+*Correct:* The `redpanda.yaml` file contains configuration parameters.
++
+*Incorrect:* `redpanda.yaml` contains configuration parameters.
diff --git a/.hyperlint/reviewer/custom-style-guide/grammar.adoc b/.hyperlint/reviewer/custom-style-guide/grammar.adoc
new file mode 100644
index 0000000000..550c282453
--- /dev/null
+++ b/.hyperlint/reviewer/custom-style-guide/grammar.adoc
@@ -0,0 +1,6 @@
+= Redpanda Data Grammar Guidelines
+
+Here are some high level guidelines for additions to the documentation:
+- Check for spelling and grammar issues.
+- Consider readability and clarity when writing.
+- Avoid long or wordy sentences.
\ No newline at end of file
diff --git a/.hyperlint/reviewer/custom-style-guide/styles.adoc b/.hyperlint/reviewer/custom-style-guide/styles.adoc
new file mode 100644
index 0000000000..6a4b36c18b
--- /dev/null
+++ b/.hyperlint/reviewer/custom-style-guide/styles.adoc
@@ -0,0 +1,35 @@
+= Redpanda Data Documentation Style Guidelines
+
+=== Notes and warnings
+
+Redpanda product documentation uses AsciiDoc note and warning admonitions:
+
+[cols="1,1",options="header"]
+|===
+| Notice | Description
+
+| NOTE
+| A supplement to the documentation with helpful information.
+
+| TIP
+| Describes a way to make things easier or indicates a best practice.
+
+| CAUTION
+| A warning that certain behavior is unexpected or may have unintended consequences.
+
+| IMPORTANT
+| An important note.
+|===
+
+== Numbers
+
+For whole numbers between one and nine, spell out the number (for example, nine instead of 9). For numbers greater than 9, or any decimal or negative number, use Arabic numerals (for example, 1.5 or -2).
+
+* *Correct:* To run Redpanda in a three-node cluster, use this command: `rpk container start -n 3`
+* *Incorrect:* To run Redpanda in a 3-node cluster, use this command: `rpk container start -n 3`
+
+The exception to this is within code or when you’re referring to a default value. For example:
+
+* *Correct:* cloud_storage_upload_ctrl_d_coeff - The derivative coefficient for the upload controller. Default is 0.
+* *Incorrect:* cloud_storage_upload_ctrl_d_coeff - The derivative coefficient for the upload controller. Default is zero.
+
diff --git a/.hyperlint/reviewer/vale-style-guide/.vale.ini b/.hyperlint/reviewer/vale-style-guide/.vale.ini
new file mode 100644
index 0000000000..3a1a62b7fd
--- /dev/null
+++ b/.hyperlint/reviewer/vale-style-guide/.vale.ini
@@ -0,0 +1,26 @@
+StylesPath = styles
+
+Packages = Google
+# Use packages to add default rules published by the community
+Vocab = CustomVocab
+# This is in the config/vocabularies folder
+MinAlertLevel = warning # error, warning, suggestion
+# When conflicting rules exist, those defined in CustomStyle (listed last)
+# override those from Google and Vale. This ensures that our custom rules have the final say.
+[*]
+BasedOnStyles = Vale, Google, CustomStyle
+# Add a package here if you want to use it
+# CustomStyle is defined in the styles folder
+
+# Vale.Spelling = NO # comment this in to disable spelling checks
+# Vale.Terms = NO # comment this in to disable terms checks
+
+
+[asciidoctor]
+experimental = YES
+attribute-missing = drop
+
+[*.adoc]
+# Put ASCIIDOC specific rules here
+# Disable this rule because Google wants level 1 headings to be in sentence case.
+disable = Google.Headings-warning
diff --git a/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/MeaningfulLinkText.yml b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/MeaningfulLinkText.yml
new file mode 100644
index 0000000000..ba649415b9
--- /dev/null
+++ b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/MeaningfulLinkText.yml
@@ -0,0 +1,17 @@
+extends: existence
+message: "Rewrite the link text for `%s` to be more descriptive."
+level: warning
+ignorecase: true
+scope: raw
+nonword: true
+tokens:
+  - "link:.*\\[here\\]"
+  - "link:.*\\[this page\\]"
+  - "link:.*\\[read more\\]"
+  - "link:.*\\[see this blog post\\]"
+  - "link:.*\\[blog post\\]"
+  - "<<.*,here>>"
+  - "<<.*,this page>>"
+  - "<<.*,read more>>"
+  - "<<.*,see this blog post>>"
+  - "<<.*,blog post>>"
diff --git a/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/OptionalPlurals.yml b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/OptionalPlurals.yml
new file mode 100644
index 0000000000..4a8767d6f5
--- /dev/null
+++ b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/OptionalPlurals.yml
@@ -0,0 +1,12 @@
+extends: existence
+message: "Don't use plurals in parentheses such as in '%s'."
+link: "https://developers.google.com/style/plurals-parentheses"
+level: error
+nonword: true
+action:
+  name: edit
+  params:
+    - trim_right
+    - "(s)"
+tokens:
+  - '\b\w+\(s\)'
diff --git a/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SentenceLength.yml b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SentenceLength.yml
new file mode 100644
index 0000000000..19772ea897
--- /dev/null
+++ b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SentenceLength.yml
@@ -0,0 +1,8 @@
+description: Try to keep sentences short (< 30 words). Split up sentence if possible.
+link: https://hyperlint.com/vale/rule/sentence-length-rule/
+extends: occurrence
+message: "Try to keep sentences short (< 30 words)."
+scope: sentence
+level: suggestion
+max: 30
+token: \b(\w+)\b
diff --git a/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SwapWords.yml b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SwapWords.yml
new file mode 100644
index 0000000000..b4caf30347
--- /dev/null
+++ b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SwapWords.yml
@@ -0,0 +1,25 @@
+# See this rule for more information: https://vale.sh/docs/checks/substitution/
+extends: substitution
+ignorecase: true
+level: warning
+message: Consider using '%s' instead of '%s'
+action:
+  name: replace
+swap:
+  as well as: and
+  back end: backend
+  config: configuration
+  data center: datacenter
+  e.g.: for example
+  etc.: and so on
+  for instance: for example
+  foo: "[use meaningful name]"
+  i.e.: that is
+  master: primary|main|original|parent|publisher|leader|active
+  once: after
+  should: will|must
+  slave: secondary|worker
+  multi datacenter: multi-datacenter
+  multi-cloud: multicloud
+  on-premise: on-premises
+  on-prem: on-premises
diff --git a/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/We.yml b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/We.yml
new file mode 100644
index 0000000000..c7ac7d3622
--- /dev/null
+++ b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/We.yml
@@ -0,0 +1,11 @@
+extends: existence
+message: "Try to avoid using first-person plural like '%s'."
+link: 'https://developers.google.com/style/pronouns#personal-pronouns'
+level: warning
+ignorecase: true
+tokens:
+  - we
+  - we'(?:ve|re)
+  - ours?
+  - us
+  - let's
diff --git a/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/WeakModifiers.yml b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/WeakModifiers.yml
new file mode 100644
index 0000000000..c7241b1325
--- /dev/null
+++ b/.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/WeakModifiers.yml
@@ -0,0 +1,11 @@
+extends: existence
+message: "Avoid the use of the word `%s`, it's a weak modifier."
+level: warning
+ignorecase: true
+scope: raw
+nonword: true
+tokens:
+  - very
+  - extremely
+  - really
+  - quite
diff --git a/.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/accept.txt b/.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/accept.txt
new file mode 100644
index 0000000000..bd4f6a4468
--- /dev/null
+++ b/.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/accept.txt
@@ -0,0 +1,6 @@
+ID
+Hyperlint
+Redpanda Data
+Redpanda
+YAML
+Zookeeper
\ No newline at end of file
diff --git a/.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/reject.txt b/.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/reject.txt
new file mode 100644
index 0000000000..976ae370b7
--- /dev/null
+++ b/.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/reject.txt
@@ -0,0 +1,3 @@
+and/or
+please
+via
\ No newline at end of file
diff --git a/.hyperlint/style-guide/grammar.md b/.hyperlint/style-guide/grammar.md
deleted file mode 100644
index 04c897936e..0000000000
--- a/.hyperlint/style-guide/grammar.md
+++ /dev/null
@@ -1,2 +0,0 @@
-Check for spelling and grammar issues.
-Also consider readability and clarity of content.
\ No newline at end of file


Reviews:
user: login: JakeSCahill
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-21T09:34:10Z
user: login: JakeSCahill
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-21T09:45:06Z
user: login: JakeSCahill
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-21T09:45:34Z
user: login: JakeSCahill
body: This is great. Thanks, Bill 🚀 
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-21T09:46:55Z
user: login: JakeSCahill
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-21T09:51:17Z
user: login: bllchmbrs
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-21T16:41:04Z

Review comments:
diff_hunk: @@ -0,0 +1,23 @@
+StylesPath = styles
+
+Packages = Google
+# Use packages to add default rules published by the community
+Vocab = CustomVocab
+# This is in the config/vocabularies folder
+MinAlertLevel = warning # error, warning, suggestion
+# 
path: .hyperlint/reviewer/vale-style-guide/.vale.ini
user: login: JakeSCahill
body: ```suggestion
# When conflicting rules exist, those defined in CustomStyle (listed last)
# override those from Google and Vale. This ensures that our custom rules have the final say.
```
created_at: 2025-03-21T09:34:10Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,27 @@
+# See this rule for more information: https://vale.sh/docs/checks/substitution/
+extends: substitution
+ignorecase: true
+level: warning
+message: Consider using '%s' instead of '%s'
+action:
+  name: replace
+swap:
+  as well as: and
+  back end: backend
+  built in: built-in
+  config: configuration
+  data center: datacenter
+  e.g.: for example
+  etc.: and so on
+  for instance: for example
+  foo: "[use meaningful name]"
+  i.e.: that is
+  master: primary|main|original|parent|publisher|leader|active
+  once: after
+  should: will|must
+  slave: secondary|worker
+  multi datacenter: multi-datacenter
+  multi-cloud: multicloud
+  on-premise: on-premises
+  on-prem: on-premises
+  quickstart: quick start
path: .hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SwapWords.yml
user: login: JakeSCahill
body: ```suggestion
```
created_at: 2025-03-21T09:45:06Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,27 @@
+# See this rule for more information: https://vale.sh/docs/checks/substitution/
+extends: substitution
+ignorecase: true
+level: warning
+message: Consider using '%s' instead of '%s'
+action:
+  name: replace
+swap:
+  as well as: and
+  back end: backend
+  built in: built-in
path: .hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SwapWords.yml
user: login: JakeSCahill
body: ```suggestion
```
created_at: 2025-03-21T09:45:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,24 @@
+StylesPath = styles
+
+Packages = Google
+# Use packages to add default rules published by the community
+Vocab = CustomVocab
+# This is in the config/vocabularies folder
+MinAlertLevel = warning # error, warning, suggestion
+# When conflicting rules exist, those defined in CustomStyle (listed last)
+# override those from Google and Vale. This ensures that our custom rules have the final say.
+[*]
+BasedOnStyles = Vale, Google, CustomStyle
+# Add a package here if you want to use it
+# CustomStyle is defined in the styles folder
+
+# Vale.Spelling = NO # comment this in to disable spelling checks
+# Vale.Terms = NO # comment this in to disable terms checks
+
+
+[asciidoctor]
+experimental = YES
+attribute-missing = drop
+
+[*.adoc]
+# Put ASCIIDOC specific rules here
path: .hyperlint/reviewer/vale-style-guide/.vale.ini
user: login: JakeSCahill
body: ```suggestion
# Put ASCIIDOC specific rules here
# Disable this rule because Google wants level 1 headings to be in sentence case.
disable = Google.Headings-warning
```
created_at: 2025-03-21T09:51:16Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,27 @@
+# See this rule for more information: https://vale.sh/docs/checks/substitution/
+extends: substitution
+ignorecase: true
+level: warning
+message: Consider using '%s' instead of '%s'
+action:
+  name: replace
+swap:
+  as well as: and
+  back end: backend
+  built in: built-in
+  config: configuration
+  data center: datacenter
+  e.g.: for example
+  etc.: and so on
+  for instance: for example
+  foo: "[use meaningful name]"
+  i.e.: that is
+  master: primary|main|original|parent|publisher|leader|active
+  once: after
+  should: will|must
+  slave: secondary|worker
+  multi datacenter: multi-datacenter
+  multi-cloud: multicloud
+  on-premise: on-premises
+  on-prem: on-premises
+  quickstart: quick start
path: .hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SwapWords.yml
user: login: bllchmbrs
body: These swaps were from your style guide :) !
created_at: 2025-03-21T16:41:04Z
author_association: CONTRIBUTOR

PR comments:
user: login: CLAassistant
created_at: 2025-03-21T05:24:48Z
body: [![CLA assistant check](https://cla-assistant.io/pull/badge/signed)](https://cla-assistant.io/redpanda-data/docs?pullRequest=1023) <br/>All committers have signed the CLA.
author_association: NONE
user: login: netlify[bot]
created_at: 2025-03-21T05:25:00Z
body: ### <span aria-hidden="true">✅</span> Deploy Preview for *redpanda-docs-preview* ready!
Built [without sensitive environment variables](https://docs.netlify.com/configure-builds/environment-variables/#sensitive-variable-policy)

|  Name | Link |
|:-:|------------------------|
|<span aria-hidden="true">🔨</span> Latest commit | 37dfc77b57f4c3add0c3a79e0aeb9daef934f946 |
|<span aria-hidden="true">🔍</span> Latest deploy log | https://app.netlify.com/sites/redpanda-docs-preview/deploys/67dd369df8aafb0008c7f750 |
|<span aria-hidden="true">😎</span> Deploy Preview | [https://deploy-preview-1023--redpanda-docs-preview.netlify.app](https://deploy-preview-1023--redpanda-docs-preview.netlify.app) |
|<span aria-hidden="true">📱</span> Preview on mobile | <details><summary> Toggle QR Code... </summary><br /><br />![QR Code](https://app.netlify.com/qr-code/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1cmwiOiJodHRwczovL2RlcGxveS1wcmV2aWV3LTEwMjMtLXJlZHBhbmRhLWRvY3MtcHJldmlldy5uZXRsaWZ5LmFwcCJ9.9_f8uf6Sa_Gm4DVZFzQ9DTSChZenRia4eB8miWRcPUI)<br /><br />_Use your smartphone camera to open QR code link._</details> |
---
<!-- [redpanda-docs-preview Preview](https://deploy-preview-1023--redpanda-docs-preview.netlify.app) -->
_To edit notification comments on pull requests, go to your [Netlify site configuration](https://app.netlify.com/sites/redpanda-docs-preview/configuration/notifications#deploy-webhooks)._
author_association: NONE
user: login: bllchmbrs
created_at: 2025-03-21T16:41:13Z
body: @JakeSCahill , all signed
author_association: CONTRIBUTOR
user: login: JakeSCahill
created_at: 2025-03-21T17:14:55Z
body: > bllchmbrs

@bllchmbrs please could you click **recheck**. It seems GitHub isn't picking up that you signed.

![image](https://github.com/user-attachments/assets/8c3df91c-59ff-42af-b54e-34e16bf1ad5c)

author_association: CONTRIBUTOR
user: login: bllchmbrs
created_at: 2025-03-21T17:48:42Z
body: @JakeSCahill , signed it like 3 times at this point... Should we just open a new PR? Maybe I'm in some strange CLA purgatory where I tried to sign it on mobile and it didn't work the first time and now the CLA is confused.


---

Edit, nevermind. I got it!
author_association: CONTRIBUTOR