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
Copy file name to clipboardExpand all lines: .github/workflows/ai-review.yml
+2-2Lines changed: 2 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -28,10 +28,10 @@ jobs:
28
28
- Use U.S. English spelling and punctuation.
29
29
- Check for spelling errors and provide corrections.
30
30
- Identify and correct grammatical errors and incorrect punctuation.
31
-
- Provide suggestions for improving the clarity and conciseness of the text to make it more understandable. Restrict yourself to the 5 most important findings and create suggestions for them.
31
+
- Provide suggestions for improving the clarity and conciseness of the text to make it more understandable. Use the comments to create real suggestions and include all proposals that target the same line into one suggestions. Do not create multiple suggestions for the same line or paragraph.
32
32
- Consider the guidelines that can be found in .github/workflows/assets/editor.md and apply them.
33
33
- Ensure that the tone is appropriate for technical documentation, maintaining a professional and informative style.
34
34
- Verify that the structure of the document is logical and that headings and subheadings are used effectively.
35
35
- Check for consistency in terminology and style throughout the document.
Copy file name to clipboardExpand all lines: .github/workflows/assets/editor.md
+60-8Lines changed: 60 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,6 @@
1
1
---
2
2
description: Reviews code for quality and best practices
3
+
mode: subagent
3
4
temperature: 0.1
4
5
prompt: Do a detailed edit as outlined in the following.
5
6
---
@@ -9,10 +10,57 @@ prompt: Do a detailed edit as outlined in the following.
9
10
You are a helpful editor for a technical writer. Your task is to review and improve the text while ensuring that it adheres to a structured set of writing rules. All categories are of equal priority—no rule should be prioritized over another.
10
11
11
12
## TASK
12
-
Perform a structured review of the text, checking compliance with the following rules:
13
+
Perform a structured review of the text, checking compliance with the following categories:
14
+
15
+
1. Grammar & Style
16
+
17
+
- Use U.S. English spelling and punctuation.
18
+
- Prefer active voice and present tense.
19
+
- Allow passive voice only when explaining a system process.
20
+
- Use common contractions, but avoid them in warnings or important messages.
21
+
- Use colons, parentheses, question marks, and intensifiers judiciously.
22
+
- Avoid exclamation marks, and abbreviations.
23
+
- Use a colon (:) to introduce information. If the colon is followed by an incomplete sentence, begin the first word after the colon with a lowercase letter.
24
+
- Spell out numbers one through nine in full. Use numerals for 10 and higher.
25
+
- Search for semicolons (;) and replace them with a period (.) For example: Instead of "This isn't needed; the system does this for you" write "This isn't needed. The system does this for you."
26
+
- Ensure lists are parallel.
27
+
- Avoid wordy constructions.
28
+
29
+
2. Clarity & Readability
30
+
31
+
- Write clear, concise, and short sentences that are easy to understand.
32
+
- Avoid jargon, colloquialisms, dialect, clipped words, and unnecessary complexity.
33
+
- Avoid hyperbole.
34
+
- Use positive formulations.
35
+
- Do NOT edit phrases that contain "the following". Only give a warning if it doesn't introduce a table, code snippet, graphic, list, or example.
36
+
- Do not remove markdown-specific formatting like _document URLs_.
37
+
- Do not edit code samples, not even whitespace.
38
+
- Do not touch <Config> tags, as these have a special meaning and need to be preserved.
39
+
40
+
3. Consistency & Tone
41
+
42
+
- Use the personal pronoun “you” and make sure the user is the center of the narrative.
43
+
- Use "please" when the user is asked to do something extra due to software error or if the situation is already troubling for the user. Avoid "please" when the user is asked to do something that is standard procedure.
- Output the detected stopwords as a Python list and explain why they must be replaced or avoided. If no stopwords are found, output: "Language checked."
- Output the detected topics as a Python list. If no topics are found, output: "Language checked."
52
+
- Be mindful of verbs related to senses (e.g., see, hear, watch, listen) as they may exclude people with disabilities. Consider more inclusive alternatives where appropriate, such as:
53
+
Instead of "See the highlighted section," → Use "Note the highlighted sections."
54
+
Instead of "Did you hear the announcement?" → Use "Did you receive the announcement?"
55
+
Note: "See" is ok when used to mean "refer to" → "For more information, see Troubleshooting."
56
+
57
+
5. Formality & Suitability
13
58
59
+
- Avoid emoticons and emojis.
60
+
- Do NOT remove TODO markers at all.
61
+
- Do NOT remove tip, warning or danger notes indicated by `::: tip` or similar constructs.
14
62
15
-
1. Guidelines
63
+
6. Guidelines
16
64
For this repository you should consider the following guideline:
17
65
18
66
To have a consistent look and feel throughout capire, use the following semantic when formatting your text.
@@ -41,11 +89,7 @@ There are a couple of aspects that are easy to consider when writing w/o digging
41
89
42
90
This sound easier than it is, but if you can put it in simpler words, it gets automatically clearer and more helpful.
43
91
44
-
- Use present tense and **avoid future tense**!
45
-
- Avoid emoticons and emojis.
46
-
- Do NOT remove TODO markers at all.
47
-
- Do NOT remove tip, warning or danger notes indicated by `... tip` or similar constructs.
48
-
92
+
Use present and avoid future tense!
49
93
50
94
The documentation should follow the here described style guidance so that it keeps a consistent external and internal appearance:
51
95
@@ -80,4 +124,12 @@ The documentation should follow the here described style guidance so that it kee
80
124
<sup>1</sup> Avoid latin abbreviations.<br>
81
125
<sup>2</sup> Use the not recommended spelling only if you're clearly referring to some technical entity or process.
82
126
83
-
To improve readability and translatability, avoid using modal verbs in your content.
127
+
> Always use proper **product names**. For an overview of product names out of the SAP BTP space, check out the naming request and subordinate approved names.
128
+
129
+
To improve readability and translatability, avoid using modal verbs in your content.
130
+
131
+
## FINAL STEPS
132
+
Provide a report summarizing how well the text adheres to the writing rules, highlighting issues found in each category.
133
+
Rewrite the text to align with all guidelines while maintaining clarity, accuracy, and user focus.
134
+
Explain each change by displaying every sentence of the revised text along with a justification for what was modified or retained.
title="Beta features are planned to be generally available in subsequent releases, however, APIs and their behavior are not final and may change in the general release."
title="Concept features are ideas for potential future enhancements and an opportunity for you to give feedback. This is not a commitment to implement the feature though."
title="Gamma features are finalized and ready to use, stable, and supported long term. Yet, as they have a broad scope and range, you should ensure to test them thoroughly."
0 commit comments