Prefer plain language in documentation

.github/copilot-instructions.md

@@ -87,6 +87,7 @@ When editing or creating markdown documents:
 - No contrastive framing ("not just X, it's Y", "goes beyond", "more than just"). Describe directly.
 - No rhetorical questions followed by obvious answers. State the assertion directly.
 - Prefer lists and tables over long paragraphs.
+- Prefer plain, widely understood vocabulary for non-native English speakers. Follow the `documentation-style` skill for examples and exceptions that preserve technical precision.
 - Prefer descriptive names and links over invented identifiers. Follow the `documentation-style` skill for exceptions required by artifact-specific rules and for preserving existing references.
 
 ---

.github/instructions/documentation-style.instructions.md

@@ -16,5 +16,6 @@ When editing markdown documentation, follow these formatting rules:
 - Do not use promotional language: "it's not just X, it's Y", "goes beyond...", "more than just...". Describe directly.
 - Do not use rhetorical questions followed by obvious answers. State the assertion directly.
 - Prefer lists and tables over long paragraphs.
+- Prefer plain, widely understood vocabulary for non-native English speakers. Follow the `documentation-style` skill for examples and exceptions that preserve technical precision.
 - Prefer descriptive names and links over invented identifiers. Follow the `documentation-style` skill for exceptions required by artifact-specific rules and for preserving existing references.
 - For diagrams (design, review, Mermaid platform rendering, tool selection), follow the `diagram-design` skill.

.github/plugins/devsquad/hooks/templates/.github/copilot-instructions.md

@@ -94,4 +94,5 @@ When editing or creating markdown documents:
 - No contrastive framing ("not just X, it's Y", "goes beyond", "more than just"). Describe directly.
 - No rhetorical questions followed by obvious answers. State the assertion directly.
 - Prefer lists and tables over long paragraphs.
+- Prefer plain, widely understood vocabulary for non-native English speakers. Follow the `documentation-style` skill for examples and exceptions that preserve technical precision.
 - Prefer descriptive names and links over invented identifiers. Follow the `documentation-style` skill for exceptions required by artifact-specific rules and for preserving existing references.

.github/plugins/devsquad/hooks/templates/.github/instructions/documentation-style.instructions.md

@@ -16,6 +16,7 @@ When editing markdown documentation, follow these formatting rules:
 - Do not use promotional language: "it's not just X, it's Y", "goes beyond...", "more than just...". Describe directly.
 - Do not use rhetorical questions followed by obvious answers. State the assertion directly.
 - Prefer lists and tables over long paragraphs.
+- Prefer plain, widely understood vocabulary for non-native English speakers. Follow the `documentation-style` skill for examples and exceptions that preserve technical precision.
 - Prefer descriptive names and links over invented identifiers. Follow the `documentation-style` skill for exceptions required by artifact-specific rules and for preserving existing references.
 - Mermaid: detect the platform via the remote (`git config --get remote.origin.url`).
   - Azure DevOps (`dev.azure.com` or `visualstudio.com`): use `:::mermaid` and `:::`

.github/plugins/devsquad/skills/documentation-style/SKILL.md

@@ -28,6 +28,7 @@ This guide defines standards for all documentation generated in the project.
   - "goes beyond..."
 - Describe directly what something is, without negating or minimizing alternatives.
 - Use active voice and direct sentences.
+- Prefer plain, widely understood vocabulary so non-native English speakers can follow the document. Use "place" or "location" instead of "locus", "use" instead of "utilize", and "make easier" instead of "facilitate" when the meaning is unchanged. Keep precise domain terms, API names, code identifiers, and verbatim quotations. Explain necessary unfamiliar terms on first use instead of replacing them with a less accurate word.
 - Avoid generic framing: if the sentence works in any project without modification, it is not saying anything useful.
   - **Avoid**: rhetorical questions followed by an obvious answer ("The solution? Test everything that matters.")
   - **Prefer**: go straight to the statement with project-specific context.

docs/src/content/docs/skills/quality.mdx

@@ -160,6 +160,9 @@ For generated work item titles, the `work-item-creation` skill explicitly exclud
 | Rhetorical questions with obvious answers | Direct assertions |
 | Generic framing (works in any project) | Project-specific context |
 | Passive voice | Active voice, direct sentences |
+| Academic or uncommon wording such as "locus" or "utilize" | Plain words such as "location" or "use" when meaning is unchanged |
+
+Use wording that non-native English speakers can follow. Preserve precise domain terms, API names, code identifiers, and verbatim quotations, and explain necessary unfamiliar terms on first use.
 
 **Document structure:** Start with the most important content (conclusion, decision, summary). Use consistent hierarchical headings. Include metadata when relevant (Status, Date, Version).