|
| 1 | +# Copilot Instructions for Microsoft Learn |
| 2 | + |
| 3 | +These instructions define a unified style and process standard for authoring and maintaining learn.microsoft.com documentation with GitHub Copilot or other AI assistance. |
| 4 | + |
| 5 | +## Learn-wide Instructions |
| 6 | + |
| 7 | +Below are instructions that apply to all Microsoft Learn documentation authored with AI assistance. Learn product team will update this periodically as needed. Each repository SHOULD NOT update this to avoid being overwritten, but update the repository-specific instructions below as needed. |
| 8 | + |
| 9 | +### AI Usage & Disclosure |
| 10 | +All Markdown content created or substantially modified with AI assistance must include an `ai-usage` front matter entry: |
| 11 | +- `ai-usage: ai-generated` – AI produced the initial draft with minimal human authorship |
| 12 | +- `ai-usage: ai-assisted` – Human-directed, reviewed, and edited with AI support |
| 13 | +- Omit only for purely human-authored legacy content |
| 14 | + |
| 15 | +If missing, **add it**. However, do not add or update the ai-usage tag if the changes proposed are confined solely to: |
| 16 | +- Links (link text and/or URLs) |
| 17 | +- Single words or short phrases, such as entries in table cells |
| 18 | +- Less than 5% of the article's word count |
| 19 | + |
| 20 | +### Writing Style |
| 21 | + |
| 22 | +Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/) with these specifics: |
| 23 | + |
| 24 | +#### Voice and Tone |
| 25 | + |
| 26 | +- Active voice, second person addressing reader directly |
| 27 | +- Conversational tone with contractions |
| 28 | +- Present tense for instructions/descriptions |
| 29 | +- Imperative mood for instructions ("Call the method" not "You should call the method") |
| 30 | +- Use "might" instead of "may" for possibility |
| 31 | +- Avoid "we"/"our" referring to documentation authors |
| 32 | + |
| 33 | +#### Structure and Format |
| 34 | + |
| 35 | +- Sentence case headings (no gerunds in titles) |
| 36 | +- Be concise, break up long sentences |
| 37 | +- Oxford comma in lists |
| 38 | +- Number all ordered list items as "1." (not sequential numbering like "1.", "2.", "3.", etc.) |
| 39 | +- Complete sentences with proper punctuation in all list items |
| 40 | +- Avoid "etc." or "and so on" - provide complete lists or use "for example" |
| 41 | +- No consecutive headings without content between them |
| 42 | + |
| 43 | +#### Formatting Conventions |
| 44 | + |
| 45 | +- **Bold** for UI elements |
| 46 | +- `Code style` for file names, folders, custom types, non-localizable text |
| 47 | +- Raw URLs in angle brackets |
| 48 | +- Use relative links for files in this repo |
| 49 | +- Remove `https://learn.microsoft.com/en-us` from learn.microsoft.com links |
| 50 | + |
| 51 | +## Repository-Specific Instructions |
| 52 | + |
| 53 | +Below are instructions specific to this repository. These may be updated by repository maintainers as needed. |
| 54 | + |
| 55 | +<!--- Add additional repository level instructions below. Do NOT update this line or above. ---> |
| 56 | + |
| 57 | + |
0 commit comments