You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add style guidance on avoiding 'should' and unnecessary parentheses
Based on feedback from lennessyy on PR #4029:
- Added guidance to avoid 'should' in user instructions; use imperative mood instead
- Added guidance to avoid unnecessary parentheses; prefer commas for clarifying information
- Provided examples of correct/incorrect usage for both patterns
- Clarified when parentheses are still appropriate (abbreviations, technical specs, etc.)
Copy file name to clipboardExpand all lines: .long_term_context/style/client_style_guide.md
+26Lines changed: 26 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -98,6 +98,32 @@ In most cases when providing direct instruction, the imperative works better.
98
98
- Correct: Next, add the following code:
99
99
- Incorrect: Next, we add the following code:
100
100
101
+
### Avoid "should" in user instructions
102
+
103
+
When giving instructions to users, use the imperative mood directly rather than saying users "should" do something. This makes instructions clearer and more direct.
104
+
105
+
- Correct: "Provide a reason when resetting, as it will be recorded in the Event History."
106
+
- Incorrect: "You should provide a reason when resetting."
107
+
108
+
Note: It's acceptable to use "should" when describing general best practices, system behavior, or outcomes (e.g., "the reader should have a usable environment").
109
+
110
+
### Avoid unnecessary parentheses
111
+
112
+
When adding clarifying or supplementary information, prefer using commas instead of parentheses. This keeps the text flow more natural and readable.
113
+
114
+
- Correct: "Reset only works if you've fixed the underlying issue, such as removing non-deterministic code."
115
+
- Incorrect: "Reset only works if you've fixed the underlying issue (such as removing non-deterministic code)."
116
+
117
+
Remove parenthetical clarifications entirely if they're not essential to understanding the instruction.
118
+
119
+
- Correct: "Select the Event ID to reset to"
120
+
- Incorrect: "Select the Event ID to reset to (typically a `WorkflowTaskCompleted` event before the failure)"
121
+
122
+
Parentheses are still appropriate for:
123
+
- Abbreviations on first use: "Transport Layer Security (TLS)"
124
+
- Technical specifications: "at least 2048-bit RSA"
125
+
- Aside notes that are truly supplementary and would break sentence flow otherwise
126
+
101
127
### Focus on specific outcomes rather than "Learn to/Learn how to" language.
102
128
103
129
Focus on the skill the learner will gain rather than the act of gaining the skill. Look for "learn to/learn how to" and remove them and you'll have tighter sentences.
0 commit comments