From 17492577133cb1d8de84c74fc96487a107330a72 Mon Sep 17 00:00:00 2001 From: Fernando de Oliveira <5161098+fedeoliv@users.noreply.github.com> Date: Fri, 16 Oct 2026 17:39:19 -0400 Subject: [PATCH] chore(authoring): prefer plain vocabulary (#40) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 40bf5936-fdf2-408a-afe7-dd07b66ed7da --- .github/copilot-instructions.md | 1 + .github/instructions/documentation-style.instructions.md | 1 + .../devsquad/hooks/templates/.github/copilot-instructions.md | 1 + .../.github/instructions/documentation-style.instructions.md | 1 + .github/plugins/devsquad/skills/documentation-style/SKILL.md | 1 + docs/src/content/docs/skills/quality.mdx | 3 +++ 6 files changed, 8 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 586ea5e..08a94ce 100644 --- a/.github/copilot-instructions.md +++ b/.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. --- diff --git a/.github/instructions/documentation-style.instructions.md b/.github/instructions/documentation-style.instructions.md index 7702932..989af02 100644 --- a/.github/instructions/documentation-style.instructions.md +++ b/.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. diff --git a/.github/plugins/devsquad/hooks/templates/.github/copilot-instructions.md b/.github/plugins/devsquad/hooks/templates/.github/copilot-instructions.md index 0426ac8..8495d02 100644 --- a/.github/plugins/devsquad/hooks/templates/.github/copilot-instructions.md +++ b/.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. diff --git a/.github/plugins/devsquad/hooks/templates/.github/instructions/documentation-style.instructions.md b/.github/plugins/devsquad/hooks/templates/.github/instructions/documentation-style.instructions.md index 82f4078..db4304b 100644 --- a/.github/plugins/devsquad/hooks/templates/.github/instructions/documentation-style.instructions.md +++ b/.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 `:::` diff --git a/.github/plugins/devsquad/skills/documentation-style/SKILL.md b/.github/plugins/devsquad/skills/documentation-style/SKILL.md index 94c2825..2812889 100644 --- a/.github/plugins/devsquad/skills/documentation-style/SKILL.md +++ b/.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. diff --git a/docs/src/content/docs/skills/quality.mdx b/docs/src/content/docs/skills/quality.mdx index 122929c..441dfcd 100644 --- a/docs/src/content/docs/skills/quality.mdx +++ b/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).