Skip to content

Commit 5e6260c

Browse files
committed
Updates to playbook guide
1 parent 22a38e2 commit 5e6260c

1 file changed

Lines changed: 19 additions & 7 deletions

File tree

docs/playbook-guide.md

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@
6464
- Bad: "get a comprehensive report with all the details", better: "get a concise report with the
6565
necessary details to fix the issues".
6666
- Avoid long sentences. Sentences over 130 characters need to be very clear otherwise. Never go beyond 160 characters.
67+
- Use badrap.io always instead of Badrap, unless the text needs to refer to the actual legal entity (Badrap Oy).
6768

6869
## Playbook design principles
6970

@@ -127,17 +128,28 @@ Categorize the checks to the following categories:
127128

128129
Also follow these rules:
129130

130-
- Follow the category structure above when outputting results. Don't invent new subcategories. You may, however, include a summary of the findings at the end
131-
- When looking at the source code, understand that some of the playbook metadata can be included from other files
132-
- Be precise when listing violations. Make sure you refer to the exact part of the guide
131+
- Follow the category structure above when outputting results. Don't invent new subcategories. You may, however, include a summary of the findings at the end.
132+
- When looking at the source code, understand that some of the playbook metadata can be included from other files.
133+
- Be precise when listing violations. Make sure you refer to the exact part of the guide.
133134
- Don't confuse the sections. When the playbook violates linting rules, list the finding there and not under a wrong section, for example under design principle check in this case.
134135
- Warn if the same requirement is covered by several sections in this guide. In that case you can list the violation under both matched categories.
135136

136-
Remember to check also these in language checks:
137+
Remember these when checking language issues:
137138

139+
- Do not report non-issues in the reveiw, just issues.
138140
- When checking sentence lenght, remember that a period, exclamation mark and questionmark signifies the end of the sentence.
139-
- When flagging a long sentence, display the original version and suggest new wording
140-
- Spot misuse of the apostrophe. Flag if the text says for example "users" when the context looks like it should say "user's"
141+
- When flagging a long sentence, display the original version and suggest new wording.
142+
- Spot misuse of the apostrophe. Flag if the text says for example "users" when the context looks like it should say "user's", e.g. the apostrophe is missing or in the wrong place.
141143
- Check for incorrect terminal punctuation marks at the end of sentences (periods, question marks, exclamation points)
142-
and flag any that don't match the sentence's intended meaning or grammatical structure
144+
and flag any that don't match the sentence's intended meaning or grammatical structure.
143145
- When reviewing lists, ensure all items are punctuated consistently, whether with commas, semicolons, or no punctuation at all.
146+
- When looking at the source code, understand that ' equals to apostrophe
147+
- Find space-will-be-missing issues when reviewing .tsx files. Carefully check every line that ends with a closing HTML tag (like `</em>`, `</strong>`,
148+
`</a>`, etc.) - if text continues on the immediately following line without any explicit space character or JSX space expression `{" "}`, this will cause missing spaces in the rendered output. See the examples below.
149+
150+
Space-will-be-missing issue examples
151+
152+
<p>
153+
If you&apos;re an <em>automation</em> or <em>full service</em>
154+
subscriber, you have access...
155+
</p>

0 commit comments

Comments
 (0)