Skip to content

Commit f8f33b2

Browse files
adegeoadegeo
authored
Create documentation editor agent instructions (#2147)
* Create documentation editor agent instructions Added detailed editing instructions for LLMs to follow the Microsoft Style Guide while ensuring technical accuracy. * Try creating a few agents
1 parent 9e6eb1b commit f8f33b2

File tree

4 files changed

+156
-4
lines changed

4 files changed

+156
-4
lines changed

‎.github/prompts/Editing.FullPass.prompt.md‎ renamed to ‎.github/agents/doceditor.agent.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
---
2-
model: Claude Sonnet 4 (copilot)
3-
mode: agent
4-
description: "Performs comprehensive editing pass following Microsoft Style Guide"
2+
name: Documentation Editor
3+
description: Edit and transform a document using the Microsoft Style Guide
54
---
65

76
# Article Editing Instructions for LLMs

‎.github/agents/planner.agent.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
name: Issue Planner
3+
description: Examines an issue and develops a plan of action to address it.
4+
---
5+
6+
# Create a plan to fix an issue
7+
8+
- Examine an issue and open a pull request that designs a comprehensive plan to solve the issue
9+
- Put the plan in a comment
10+
- Don't change files or execute the plan

‎.github/agents/snippets.migration.agent.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
name: Snippets Migration
3+
description: Migrate code from the old ~/samples/snippets/ location to the relative ./snippets location.
4+
---
5+
6+
# Migrate code snippets
7+
8+
**IMPORTANT**: Unless otherwise asked to, **only** edit the article file in context. At the end of your operations you may ask for permission to edit other articles referencing the same snippets.
9+
10+
## Repository structure for code snippets
11+
12+
**IMPORTANT**: This repository has TWO different locations for code snippets:
13+
14+
### Old location (legacy - to be migrated FROM)
15+
- Path: `~/samples/snippets/`
16+
- Example: `~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.Clipboard/CS/form1.cs`
17+
- Status: Legacy, should be migrated to new location
18+
19+
### New location (current standard - migrate TO)
20+
- Path pattern: `./snippets/{doc-file}/[net-or-framework]/{code-language}/`
21+
- Example: `./snippets/how-to-add-data-to-the-clipboard/net/csharp/form1.cs`
22+
23+
**Path components explained:**
24+
- `{doc-file}`: The markdown article filename WITHOUT the `.md` extension
25+
- Example: For article `how-to-add-data-to-the-clipboard.md` → use `how-to-add-data-to-the-clipboard`
26+
- `[net-or-framework]`: Choose based on target framework:
27+
- `net`: For .NET (.NET 6 and newer)
28+
- `framework`: For .NET Framework (4.8 and older)
29+
- **Rule**: Only include this subfolder when the article demonstrates BOTH .NET and .NET Framework approaches
30+
- `{code-language}`:
31+
- `csharp`: For C# code
32+
- `vb`: For Visual Basic code
33+
34+
## Legacy code characteristics (migrate FROM these)
35+
36+
**Location**: `~/samples/snippets/` folder
37+
**Problems with legacy code:**
38+
- Written for .NET Framework (outdated)
39+
- Often incomplete or non-compilable
40+
- May lack project files
41+
- Uses outdated syntax and patterns
42+
43+
**Legacy article references look like this:**
44+
```markdown
45+
[!code-{code-language}[description](~/samples/snippets/{path-to-file}#{snippet-identifier})]
46+
```
47+
48+
## Current code requirements (migrate TO these)
49+
50+
**Location**: `./snippets/{doc-file}/[framework]/{code-language}/`
51+
52+
**Requirements for current code standards:**
53+
- ✅ MUST be complete and compilable
54+
- ✅ MUST include a project file
55+
- ✅ MUST target appropriate .NET version (see targeting rules below)
56+
- ✅ MUST provide BOTH C# and Visual Basic versions
57+
- ✅ MUST use appropriate syntax for the target framework
58+
- ✅ MUST use meaningful, descriptive snippet identifiers in CamelCase format
59+
- **Examples** of good snippet identifiers: `BasicClipboardData`, `CustomDataFormat`, `ClipboardImageHandling`
60+
- **Avoid** simplistic identifiers like `1`, `2`, `code1`, or `snippet1`
61+
62+
**Current article references look like this:**
63+
```markdown
64+
:::code language="{code-language}" source="{file-path}" id="{snippet-identifier}":::
65+
```
66+
67+
**Framework targeting rules:**
68+
- **Migration vs. Modernization**:
69+
- **Migration**: Move code to new location with minimal changes
70+
- **Modernization**: Update code to use latest .NET features and best practices
71+
- **When to migrate only**: When article has `ms.service: dotnet-framework` frontmatter or is specifically about .NET Framework features
72+
- **When to modernize**: When article demonstrates both .NET and .NET Framework, or when specifically requested
73+
- **Default targeting**:
74+
- For .NET Framework-specific articles: Keep targeting .NET Framework
75+
- For general articles: Target latest .NET version (e.g., .NET 10)
76+
- For mixed articles: Create separate snippets in `net/` and `framework/` subfolders
77+
78+
## Migration steps (follow in order)
79+
80+
**WHEN TO MIGRATE**: Migrate code when you encounter articles with references to `~/samples/snippets/` paths.
81+
82+
**STEP-BY-STEP PROCESS:**
83+
84+
### 1. Analyze existing code and article context
85+
- **Find**: Locate the legacy snippet file in `~/samples/snippets/`
86+
- **Check frontmatter**: Look for `ms.service: dotnet-framework` in the article's frontmatter
87+
- **Determine scope**:
88+
- If frontmatter has `ms.service: dotnet-framework` → this is likely a .NET Framework-specific article
89+
- if frontmatter has `ms.service: dotnet-desktop` or similar → this is likely a dual-framework or general article
90+
- If article demonstrates both .NET and .NET Framework → prepare for dual targeting
91+
- If article is general purpose → consider targeting current .NET
92+
- **Identify**: Determine the programming language (C# or Visual Basic)
93+
- **Extract**: Note the snippet identifier used in the article reference
94+
95+
### 2. Create new folder structure
96+
- **Pattern**: `./snippets/{doc-file}/[net-or-framework]/{code-language}/`
97+
- **Example**: For article `clipboard-operations.md` → create `./snippets/clipboard-operations/net/csharp/`
98+
- **Decision tree for framework folder**:
99+
- Article has `ms.service: dotnet-framework` frontmatter → use `./snippets/{doc-file}/framework/{code-language}/`
100+
- Article shows ONLY current .NET examples → use `./snippets/{doc-file}/{code-language}/` (omit framework folder)
101+
- Article shows BOTH .NET and .NET Framework → create both `./snippets/{doc-file}/net/{code-language}/` and `./snippets/{doc-file}/framework/{code-language}/`
102+
103+
### 3. Migrate and update code
104+
- **Copy**: Copy only the snippet code (and any supporting code to compile the snippet) to the new location
105+
- **Update approach**:
106+
- **For .NET Framework articles**: Migrate with minimal changes, keep .NET Framework targeting
107+
- **For dual-framework articles**: Create both versions with appropriate targeting and update frontmatter to `ms.service: dotnet-desktop`
108+
- **For general articles**: Update to target current .NET only if specifically requested or if article demonstrates modernization
109+
- **Complete**: Ensure code is fully functional and compilable
110+
- **Project file**: Create or update project file with appropriate target framework
111+
112+
### 4. Create both language versions
113+
- **Requirement**: MUST provide both C# and Visual Basic versions
114+
- **C# path**: `./snippets/{doc-file}/[framework]/csharp/`
115+
- **VB path**: `./snippets/{doc-file}/[framework]/vb/`
116+
117+
### 5. Update article references
118+
- **Replace**: Change from legacy `[!code-...]` format to modern `:::code...:::` format
119+
- **Before**: `[!code-csharp[description](~/samples/snippets/path/file.cs#snippet1)]`
120+
- **After**: `:::code language="csharp" source="./snippets/doc-name/net/csharp/file.cs" id="BasicClipboardData":::`
121+
- **Note**: Use meaningful CamelCase identifiers instead of simple numbers
122+
123+
### 6. Validate
124+
- **Build**: Ensure all code compiles successfully
125+
- **Test**: Verify snippet references work in the article
126+
- **Clean**: Remove unused legacy files (if no other articles reference them)
127+
128+
### 7. Delete
129+
- **Identify**:
130+
- Check if the old snippet file is used by any other articles
131+
- Some articles may use a relative path to the `samples` folder, so simply search for links to `samples/snippets/...`
132+
- Be confident that all legacy snippets use a `samples/snippets` folder structure
133+
- **Delete**: If old snippet is no longer used by any article, delete it.
134+
135+
## Common mistakes to avoid
136+
137+
- ❌ **Don't** assume all code needs to be modernized - check article context first
138+
- ❌ **Don't** modernize .NET Framework-specific articles unless specifically requested
139+
- ❌ **Don't** ignore the `ms.service: dotnet-framework` frontmatter indicator
140+
- ❌ **Don't** forget to create both C# and VB versions
141+
- ❌ **Don't** mix up the framework targeting (net vs framework)
142+
- ❌ **Don't** forget to update ALL article references to the migrated code
143+
- ❌ **Don't** leave incomplete or non-compilable code

‎.github/copilot-instructions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ Use tabbed content when the differences are code-based:
7272
```
7373

7474
### Use Pivots
75-
Use zone pivots when there are conceptual differences that can't easily be explained with tabs and a note. Pivots allow for more comprehensive explanations of different approaches or methodologies.
75+
Use zone pivots when there are many conceptual differences that can't easily be explained with tabs and a note. Pivots allow for more comprehensive explanations of different approaches or methodologies.
7676

7777
To use zone pivots:
7878

0 commit comments

Comments
 (0)