Skip to content

Commit 0ff5ec9

Browse files
bllchmbrsJakeSCahill
bllchmbrs
and
JakeSCahill
authored
Redpanda Style Guide (#1023)
Co-authored-by: Jake Cahill <[email protected]>
1 parent a5e40a1 commit 0ff5ec9

File tree

15 files changed

+184
-5
lines changed

15 files changed

+184
-5
lines changed

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ poc-docs/
99
docs/
1010
.docusaurus
1111
testResults*.json
12+
.hyperlint/reviewer/vale-style-guide/styles/Google/

‎.hyperlint/config.yaml

+8-3
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11
content_dir: "/modules"
2-
custom_style_guide:
3-
enabled: true
4-
path_to_style_guide_dir: "./.hyperlint/style-guide/"
2+
reviewer:
3+
custom_style_guide:
4+
enabled: true
5+
path_to_style_guide_dir: .hyperlint/reviewer/custom-style-guide
6+
vale_style_guide:
7+
check_status_upon_review_failure: failure
8+
enabled: true
9+
path_to_vale_ini_file: .hyperlint/reviewer/vale-style-guide/.vale.ini

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

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
= Redpanda Data Documentation Code Formatting Guidelines
2+
3+
=== Commands and code
4+
5+
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".
6+
+
7+
*Correct:* Run the `rpk topic create` command to create a new topic.
8+
+
9+
*Incorrect:* `rpk topic create` creates a new topic.
10+
11+
Similarly, do not start a sentence with a filename.
12+
+
13+
*Correct:* The `redpanda.yaml` file contains configuration parameters.
14+
+
15+
*Incorrect:* `redpanda.yaml` contains configuration parameters.

‎.hyperlint/reviewer/custom-style-guide/grammar.adoc

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
= Redpanda Data Grammar Guidelines
2+
3+
Here are some high level guidelines for additions to the documentation:
4+
- Check for spelling and grammar issues.
5+
- Consider readability and clarity when writing.
6+
- Avoid long or wordy sentences.

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

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
= Redpanda Data Documentation Style Guidelines
2+
3+
=== Notes and warnings
4+
5+
Redpanda product documentation uses AsciiDoc note and warning admonitions:
6+
7+
[cols="1,1",options="header"]
8+
|===
9+
| Notice | Description
10+
11+
| NOTE
12+
| A supplement to the documentation with helpful information.
13+
14+
| TIP
15+
| Describes a way to make things easier or indicates a best practice.
16+
17+
| CAUTION
18+
| A warning that certain behavior is unexpected or may have unintended consequences.
19+
20+
| IMPORTANT
21+
| An important note.
22+
|===
23+
24+
== Numbers
25+
26+
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).
27+
28+
* *Correct:* To run Redpanda in a three-node cluster, use this command: `rpk container start -n 3`
29+
* *Incorrect:* To run Redpanda in a 3-node cluster, use this command: `rpk container start -n 3`
30+
31+
The exception to this is within code or when you’re referring to a default value. For example:
32+
33+
* *Correct:* cloud_storage_upload_ctrl_d_coeff - The derivative coefficient for the upload controller. Default is 0.
34+
* *Incorrect:* cloud_storage_upload_ctrl_d_coeff - The derivative coefficient for the upload controller. Default is zero.
35+

‎.hyperlint/reviewer/vale-style-guide/.vale.ini

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
StylesPath = styles
2+
3+
Packages = Google
4+
# Use packages to add default rules published by the community
5+
Vocab = CustomVocab
6+
# This is in the config/vocabularies folder
7+
MinAlertLevel = warning # error, warning, suggestion
8+
# When conflicting rules exist, those defined in CustomStyle (listed last)
9+
# override those from Google and Vale. This ensures that our custom rules have the final say.
10+
[*]
11+
BasedOnStyles = Vale, Google, CustomStyle
12+
# Add a package here if you want to use it
13+
# CustomStyle is defined in the styles folder
14+
15+
# Vale.Spelling = NO # comment this in to disable spelling checks
16+
# Vale.Terms = NO # comment this in to disable terms checks
17+
18+
19+
[asciidoctor]
20+
experimental = YES
21+
attribute-missing = drop
22+
23+
[*.adoc]
24+
# Put ASCIIDOC specific rules here
25+
# Disable this rule because Google wants level 1 headings to be in sentence case.
26+
disable = Google.Headings-warning

‎.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/MeaningfulLinkText.yml

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
extends: existence
2+
message: "Rewrite the link text for `%s` to be more descriptive."
3+
level: warning
4+
ignorecase: true
5+
scope: raw
6+
nonword: true
7+
tokens:
8+
- "link:.*\\[here\\]"
9+
- "link:.*\\[this page\\]"
10+
- "link:.*\\[read more\\]"
11+
- "link:.*\\[see this blog post\\]"
12+
- "link:.*\\[blog post\\]"
13+
- "<<.*,here>>"
14+
- "<<.*,this page>>"
15+
- "<<.*,read more>>"
16+
- "<<.*,see this blog post>>"
17+
- "<<.*,blog post>>"

‎.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/OptionalPlurals.yml

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
extends: existence
2+
message: "Don't use plurals in parentheses such as in '%s'."
3+
link: "https://developers.google.com/style/plurals-parentheses"
4+
level: error
5+
nonword: true
6+
action:
7+
name: edit
8+
params:
9+
- trim_right
10+
- "(s)"
11+
tokens:
12+
- '\b\w+\(s\)'

‎.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SentenceLength.yml

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
description: Try to keep sentences short (< 30 words). Split up sentence if possible.
2+
link: https://hyperlint.com/vale/rule/sentence-length-rule/
3+
extends: occurrence
4+
message: "Try to keep sentences short (< 30 words)."
5+
scope: sentence
6+
level: suggestion
7+
max: 30
8+
token: \b(\w+)\b

‎.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/SwapWords.yml

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# See this rule for more information: https://vale.sh/docs/checks/substitution/
2+
extends: substitution
3+
ignorecase: true
4+
level: warning
5+
message: Consider using '%s' instead of '%s'
6+
action:
7+
name: replace
8+
swap:
9+
as well as: and
10+
back end: backend
11+
config: configuration
12+
data center: datacenter
13+
e.g.: for example
14+
etc.: and so on
15+
for instance: for example
16+
foo: "[use meaningful name]"
17+
i.e.: that is
18+
master: primary|main|original|parent|publisher|leader|active
19+
once: after
20+
should: will|must
21+
slave: secondary|worker
22+
multi datacenter: multi-datacenter
23+
multi-cloud: multicloud
24+
on-premise: on-premises
25+
on-prem: on-premises

‎.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/We.yml

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
extends: existence
2+
message: "Try to avoid using first-person plural like '%s'."
3+
link: 'https://developers.google.com/style/pronouns#personal-pronouns'
4+
level: warning
5+
ignorecase: true
6+
tokens:
7+
- we
8+
- we'(?:ve|re)
9+
- ours?
10+
- us
11+
- let's

‎.hyperlint/reviewer/vale-style-guide/styles/CustomStyle/WeakModifiers.yml

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
extends: existence
2+
message: "Avoid the use of the word `%s`, it's a weak modifier."
3+
level: warning
4+
ignorecase: true
5+
scope: raw
6+
nonword: true
7+
tokens:
8+
- very
9+
- extremely
10+
- really
11+
- quite

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

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
ID
2+
Hyperlint
3+
Redpanda Data
4+
Redpanda
5+
YAML
6+
Zookeeper

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

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
and/or
2+
please
3+
via

‎.hyperlint/style-guide/grammar.md

-2
This file was deleted.

0 commit comments

Comments
 (0)