Improve Hyperlint config to avoid false positives (#1036)

Co-authored-by: Angela Simms <[email protected]>

Author: JakeSCahill

.hyperlint/reviewer/custom-style-guide/code-formatting.adoc

@@ -1,20 +1,12 @@
 = Redpanda Data Documentation Code Formatting Guidelines
 
-== Commands and code
-
-Don't start a sentence not inside a code block with a command or code. Instead, try to move the code into the middle of the sentence. For example, you can introduce the command with a more descriptive word like “Run”.
+== Rule: Do not start a sentence with a command or code.
 
 *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.
-
-This version is correct because the sentence starts with the definite article, providing a descriptive context before introducing the xref.
+This is incorrect because the sentence is starting with a command / code in backticks.
 
 *Correct:*
 
@@ -30,4 +22,12 @@ The xref:api:ROOT:admin-api.adoc#get-/v1/broker/pre_restart_probe[`pre_restart_p
 xref:api:ROOT:admin-api.adoc#get-/v1/broker/pre_restart_probe[`pre_restart_probe`] is an endpoint.
 ----
 
-This version is incorrect because it starts directly with the xref. According to our style guidelines, sentences should not begin with a command, code snippet, or filename. Instead, the xref should be integrated into a descriptive sentence.
+== Rule: Do not start a sentence with a filename.
+
+*Correct:* The `redpanda.yaml` file contains configuration parameters.
+
+*Incorrect:* `redpanda.yaml` contains configuration parameters.
+
+== Rule: Ignore AsciiDoc include directives
+
+Do not make comments on lines that begin with `include::`. This notation inserts the content from another file.

.hyperlint/reviewer/custom-style-guide/styles.adoc

@@ -1,8 +1,8 @@
 = Redpanda Data Documentation Style Guidelines
 
-=== Notes and warnings
+== Notes and warnings
 
-Redpanda product documentation uses AsciiDoc note and warning admonitions:
+Redpanda documentation uses AsciiDoc admonitions:
 
 [cols="1,1",options="header"]
 |===
@@ -28,7 +28,7 @@ For whole numbers between one and nine, spell out the number (for example, nine
 * *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:
+The exception to this is within code blocks 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

@@ -14,13 +14,13 @@ BasedOnStyles = Vale, Google, CustomStyle
 
 # Vale.Spelling = NO # comment this in to disable spelling checks
 # Vale.Terms = NO # comment this in to disable terms checks
-
+# Disable this rule because Google wants level 1 headings to be in sentence case.
+Google.Headings = NO
+Google.WordList = NO
 
 [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/We.yml

@@ -1,5 +1,5 @@
 extends: existence
-message: "Try to avoid using first-person plural like '%s'."
+message: "Try to avoid using first-person plural like '%s'. Instead use the first person singular, or rephrase the sentence to use Redpanda Data as the subject."
 link: 'https://developers.google.com/style/pronouns#personal-pronouns'
 level: warning
 ignorecase: true