Merge branch 'main' into anynewline-docs

Author: danmoseley

.github/agents/docseditor.agent.md

@@ -3,20 +3,32 @@ name: DocsEditor
 description: Edit and transform a document using the Microsoft Style Guide
 ---
 
-# Article Editing Instructions for LLMs
+# Article Writing and Editing Instructions for LLMs
 
-You are performing an edit pass on a Microsoft documentation article. Your MANDATORY goal is to aggressively transform the content to follow the Microsoft Style Guide while preserving technical accuracy and meaning.
+**Mode: EDITING** — Transform the existing article to follow the Microsoft Style Guide. Preserve all technical accuracy and meaning.
+**Mode: WRITING** — Create new content that follows the Microsoft Style Guide from the start. Ensure technical accuracy, clarity, and consistency.
+
+Determine which mode applies, then execute all mandatory transformations defined in this document.
 
 ❌ Don't provide explanations or commentary on your process unless asked; ✅ only summarize changes at the end.
 
 ## EDITING APPROACH - FOLLOW THIS METHODOLOGY
 
 1. **Read the entire document first**
-2. **Systematically scan for PATTERNS, not just exact matches** - The examples below represent common patterns; look for similar constructions throughout
-3. **Apply ALL transformations aggressively** - Don't skip patterns just because they're not exactly like the examples
-4. **Focus especially on voice, tense, and weak constructions** - These are the most commonly missed transformations
-5. **Be thorough in pattern recognition** - If you see "There are many ways to", treat it the same as "There are several ways to"
-6. **Simplify aggressively while preserving meaning** - When in doubt, choose the simpler, more direct alternative
+2. **Verify document structure** - Check that the article has a logical heading hierarchy, an introduction, and appropriate sections (such as prerequisites, steps, and next steps). Flag any missing structural elements.
+3. **Systematically scan for PATTERNS, not just exact matches** - The examples below represent common patterns; look for similar constructions throughout
+4. **Apply ALL transformations aggressively** - Don't skip patterns just because they're not exactly like the examples
+5. **Focus especially on voice, tense, and weak constructions** - These are the most commonly missed transformations
+6. **Be thorough in pattern recognition** - If you see "There are many ways to", treat it the same as "There are several ways to"
+7. **Simplify aggressively while preserving meaning** - When in doubt, choose the simpler, more direct alternative
+
+## WRITING APPROACH - FOLLOW THIS METHODOLOGY
+
+1. **Understand the requirements** - Clarify the topic, audience, and purpose
+2. **Ask for structure** - Before writing, ask the user for a template or an existing article to follow for structure
+3. **Write with style guidelines in mind** - Apply voice, tense, and formatting rules from the start
+4. **Ensure completeness** - Include all necessary sections and technical details
+5. **Validate accuracy** - Verify technical correctness and consistency
 
 ## PATTERN EXAMPLES FOR RECOGNITION
 
@@ -124,6 +136,15 @@ When editing, focus on these areas in order of priority:
 - ❌ Remove filler words: "quite", "very", "easily", "simply" (unless essential)
 - Look for ANY unnecessary prepositional phrases or filler words
 
+**SCAN FOR AND REPLACE ambiguous "this" references (these are examples - find ALL similar patterns):**
+- "This" at the start of a sentence or clause is often ambiguous — replace it with the specific noun it refers to
+- ❌ "This creates a file" → ✅ "The command creates a file"
+- ❌ "This is useful when..." → ✅ "The feature is useful when..."
+- ❌ "This can be configured by..." → ✅ "The setting can be configured by..."
+- ❌ "Configure this before deploying" → ✅ "Configure the connection string before deploying"
+- Look for ANY sentence or clause where "this" starts or is the subject, and replace it with the explicit noun
+- **NOTE:** "this" is acceptable when used as an adjective directly before a noun ("this method", "this file"), but avoid it when used alone as a pronoun
+
 **SCAN FOR AND ENSURE consistent terminology (apply this principle throughout):**
 - Pick one term for each concept and use it throughout
 - ❌ "Because" and "Since" mixed → ✅ "Because" consistently
@@ -210,18 +231,19 @@ When editing, focus on these areas in order of priority:
 - ALWAYS use no spaces around dashes: "Use pipelines—logical groups—to consolidate"
 - ALWAYS add blank lines around markdown elements (don't add extra if they exist)
 
-## FINAL VALIDATION - MANDATORY CHECKS
-
-After editing, you MUST verify:
-- [ ] ALL passive voice converted to active voice
-- [ ] ALL "you can/should" converted to imperative mood
-- [ ] ALL future tense converted to present tense for descriptions
-- [ ] ALL contractions added where appropriate
-- [ ] ALL verbose phrases simplified
-- [ ] ALL weak constructions eliminated
-- [ ] Content maintains technical accuracy
-- [ ] Tone is conversational and helpful
-- [ ] Sentences are concise and scannable
-- [ ] Formatting follows conventions
-- [ ] No consecutive headings without content
-- [ ] Code blocks are unchanged (except comments if needed)
+## API REFERENCES
+
+Use cross-references instead of plain text or raw URLs when referring to .NET APIs:
+
+- Format: `<xref:api-doc-ID>`
+- Find API doc IDs in XML files at https://github.com/dotnet/dotnet-api-docs
+  - For types: use the `Value` attribute of `<TypeSignature>` where `Language="DocId"` (omit the first 2 characters)
+  - For members: use the `Value` attribute of `<MemberSignature>` where `Language="DocId"` (omit the first 2 characters)
+- If unsure of the doc ID, use the API browser: `https://learn.microsoft.com/api/apibrowser/dotnet/search?api-version=0.2&locale=en-us&search={API_NAME}&$skip=0&$top=5` and use the `url` value from the results as a manual link.
+
+### Encoding
+
+Use the following rules to encode special characters in API doc IDs:
+
+1. Encode `#` as `%23` in API doc IDs. For example, `System.String.#ctor` becomes `System.String.%23ctor`.
+2. **DO NOT** encode `*` or \` (backtick) characters as `%2A` or `%60` respectively.

.github/copilot-instructions.md

@@ -29,12 +29,20 @@ Unless otherwise specified, all .NET content refers to modern .NET (not .NET Fra
 Use cross-references: `<xref:api-doc-ID>`.
 
 To find API doc IDs:
+
 1. Check XML files in https://github.com/dotnet/dotnet-api-docs.
 2. For types: `Value` attribute of `<TypeSignature>` where `Language="DocId"` (omit first 2 characters).
 3. For members: `Value` attribute of `<MemberSignature>` where `Language="DocId"` (omit first 2 characters).
 
 If unsure, use API browser: `https://learn.microsoft.com/api/apibrowser/dotnet/search?api-version=0.2&locale=en-us&search={API_NAME}&$skip=0&$top=5` and then use the `url` value from the results as a manual link.
 
+### Encoding
+
+Use the following rules to encode special characters in API doc IDs:
+
+- Encode `#` as `%23` in API doc IDs. For example, `System.String.#ctor` becomes `System.String.%23ctor`.
+- **DO NOT** encode `*` or \` (backtick) characters as `%2A` or `%60` respectively.
+
 ## Code Snippets
 
 For snippets >6 lines:
@@ -45,6 +53,11 @@ For snippets >6 lines:
 1. Create examples in both C# and Visual Basic unless the article referencing the snippet resides in the in the `csharp`, `fsharp`, and `visual-basic` language folders.
 1. When you add code, use code comments sparingly because they don't get localized. You can use them to briefly clarify code-specific details (such as logic, parameters, or edge cases). Put any critical information and context in the markdown text of the referencing article.
 1. IMPORTANT: For created code, always try to encapsulate it in an standalone executable (e.g. `dotnet fsi myFile.fsx` or `dotnet run myFile.cs`, add the necessary boilerplate/imports/usings where needed, and execute it.). Run it, and for every code snippet, include a PR commentary checking each code sample and proving what it has produced - this can be diagnostics, standard output, or a result value. That standalone file is just for the purpose of verification within copilot's execution environment, the published docs snippet should remain a subset as you would normally write to maximize clarity.
+1. IMPORTANT: Code snippets are referenced in the in markdown following this format: `:::code language="{code-language}" source="{relative-file-path}" id="{snippet-identifier}":::`. For example:
+   ```markdown
+   :::code language="csharp" source="./snippets/doc-name/csharp/File.cs" id="ButtonClick":::
+   :::code language="vb" source="./snippets/doc-name/vb/File.vb" id="ButtonClick":::
+   ```
 
 ## File Naming