Redpanda Style Guide

.gitignore

@@ -9,3 +9,4 @@ poc-docs/
 docs/
 .docusaurus
 testResults*.json
+.hyperlint/reviewer/vale-style-guide/styles/Google/

.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

.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.

.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.

.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.
+

.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

.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>>"

.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\)'

.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

.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

.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

.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

.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/accept.txt

@@ -0,0 +1,6 @@
+ID
+Hyperlint
+Redpanda Data
+Redpanda
+YAML
+Zookeeper

.hyperlint/reviewer/vale-style-guide/styles/config/vocabularies/CustomVocab/reject.txt

@@ -0,0 +1,3 @@
+and/or
+please
+via